MANIFOLD — User Guide

Generative just-intonation firmware for the M-VAVE FM-1

MANIFOLD turns the FM-1 into a self-playing instrument. Two layers of moving points wander over a map of a scale, and every note they pass near sounds, as loud as the points near it. Nothing is sequenced: there are no steps, no patterns and no note triggers. The motion is continuous, the loudness is continuous, and the rhythm is a continuous landscape the motion is shaded by. You steer it with four performance knobs, play into it with the keys, roll new patches with one button, and dig into every part of it from the page buttons.

Everything is in tune in a strict sense. Every note is a whole-number ratio of the scale's root (just intonation), and every partial of every note is a whole-number multiple of that note, so chords fuse instead of beating.

This guide covers installing the firmware, playing it, and every page and setting. The last part, For developers, gives the mathematics of each generator and how the code is organised.

Install

MANIFOLD is a single firmware file, manifold-VERSION.fwsc. Installing it replaces the FM-1's current firmware; you can go back to the stock firmware or any other FM-1 firmware the same way.

From the web installer (Chrome or Edge, desktop):

1. Connect the FM-1 to the computer with a USB data cable and switch it on.
2. Open the installer page on the MANIFOLD site and press Connect. Pick the FM-1 when the browser asks.
3. Press Install and wait for it to finish. The FM-1 restarts into MANIFOLD.

From the command line (with fm1-base checked out):

python3 tools/fm1_install.py manifold-VERSION.fwsc

Try it first in the browser. The MANIFOLD site has the whole firmware running in WebAssembly on a drawn FM-1 (the emu page): click the buttons, drag the knobs, play the keys with the mouse or the computer keyboard. It sounds the same as the FM-1, and patches you store there are kept in the browser.

After installing, the FM-1 starts on a fresh patch every time: a Groove-style roll on the 1-3-5-9 hexany with its root on A1. It is silent until you press PLAY (the keys play at once).

Quick start

1. Press PLAY. The two layers start moving and the patch plays itself. PLAY again stops it.
2. Turn K1–K4 on the Perform page. These are the performance knobs: Timbre, Groove, Space and Motion. Each one moves a dozen or more settings at once along its own path; the centre is the patch as rolled.
3. Play the keys. A key sounds its note and pulls the moving points toward it, so the music bends around what you play and lets go when you release.
4. Tap REC for a new sound (the scale stays). Double-tap REC to roll everything.
5. Turn PRESET to choose a style (Wild, Tongue drum, Groove, Ambient, Cosmic, Drum circle, Machine, Breaks); it rolls a new patch in that style once the knob rests.
6. Hold SAVE and press a key (1–16) to store the patch. Hold HOME and press the key to load it again. A tap on SAVE shows the Patches page: four banks of 16.
7. Hold PLAY to see the performance keys: scenes, tap tempo, fill, freeze, latch, mutes, undo and panic.

That is enough to play. The rest of this guide explains what each part does, so you can shape it.

How MANIFOLD thinks

The scale is a map

The notes of the scale are laid out like a tongue drum: the root (the ding) and the scale's notes over one to six octaves. Each note has a place on a Tonnetz, a map where neighbours are consonant: fifths run along one axis, major thirds at 60°, natural sevenths at −60°. On the Perform page this map is the square on the left; each small square is a note.

Two layers of moving points

Each layer is a generator: one to eight points that move across the map along a motion (a continuous function of time: an orbit, a chaotic flow, a run up the scale, a chord progression…). Each point also carries an envelope, a loudness that changes continuously (a pulse, a swell, its own speed, the rhythm…).

A note sounds as loud as the points near it, weighted by their envelopes. A point sitting on a note is that note; a point between two notes sounds both, crossfaded; a point crossing the map glides from note to note. Reach sets how far a point's influence spreads.

Layer 1 is drawn as crosses, layer 2 as dots. The layers can also act on each other instead of both playing (see Route).

Each layer has a voice

Every sounding note is a bank of up to 16 oscillators at exact harmonics of the note. A layer's voice (Voice 1, Voice 2) is one smooth function that sets all their levels and phases from a few controls: where the spectrum peaks, its slope, its stride, its phase pattern. Anything can move these while notes ring and the tone follows without a seam.

The rhythm is a landscape, not a grid

There is no step sequencer. The rhythm is a stream: a sum of smooth peaks at the bar, the half bar, the beat and faster divisions (in twos, in threes, or both). It shades every envelope (Grip) and its peaks above a threshold are events that the drums play. Swing, three-against-four, rotation and long-form variation are all continuous controls on that one function.

The drums ride the synth

The four drums (kick, snare, hat, tom) make no sound of their own and never change a note's pitch. A hit puts an envelope and a change of colour (brighter, snappier) on a note that the synth is already playing. So the drums are always in tune and always part of the same sound.

The screen

Every page has the same three parts.

Header. The page's name and the part of it you are on. On the right: the tempo in BPM and the transport (a triangle while it runs, a square when stopped), plus BT while Bluetooth audio streams. On the Perform page, a battery gauge sits left of the tempo: 0–3 bars, amber at one bar or none, or USB when a computer powers the FM-1. When you change something, its name and new value show in the header for a moment.

Middle. Four rows, one for each knob, K1 at the top. Each row shows the setting's name, its value in real units (Hz, ms, BPM, notes, names) and a bar. A dash means the knob does nothing on this tab.

Footer. The page's tabs; SELECT moves between them (the underlined one is shown). Below them, a reminder of what the buttons do on this page.

Color themes. Nine: Glacier, Ember, Moss, Rose, Violet, Sunset, Lagoon, Gold and Mono (Setup → General → K1).

Controls at a glance

Knobs

Page buttons

Buttons and gestures

The Perform page

The map (left). Every note of the scale where it sits on the surface. A note lights up as it sounds (brighter is louder; a held key is white and larger). Layer 1's points are crosses, layer 2's are dots; each is brighter while its envelope is up.

What is playing (right, top to bottom):

• the scale;
• the rhythm's engine (Threshold or Lock) and the surface (Plane, Torus, Sphere);
• the layers: "Orbit / Drift" when both play; when one layer shapes the other, the carrier and how it is shaped: "Lorenz x Pass" (multiplies), "Lorenz + Pass" (adds), "Ladder on Orbit" (moves);
• the style and the seed (#34334), or the patch number if one is loaded.

Chips. LATCH, FREEZE and FILL light while those performance keys are on. L1, L2, GEN and DRM are lit while layer 1, layer 2, the generators and the drums are on (DRM also flashes on each hit).

The performance knobs (bottom). Four bipolar bars. The centre is the patch as rolled.

The performance knobs

Each knob rides a path through most of the settings of its part of the instrument. Turning it does not just scale one value: every setting on the path goes its own way, and the half-way point can lean somewhere different from the end, so a full turn is a journey through several different sounds. The header shows how many settings ride the knob as you turn it.

Levels (layer levels, drum levels, master) and Temper are never on a knob. REC + HOME rolls new paths; SAVE + HOME locks them so rolls keep them. The knobs can also be turned by the modulation matrix: see Knobs as destinations. A white tick on a knob's bar shows where the matrix has it.

The performance keys

Hold PLAY: the white keys become the performance keys and the screen shows the map. Let go of PLAY to return.

Playing the keys

The keys play the scale, not the chromatic keyboard. Key 1 is a low note of the scale and each key up is the next note of the scale in pitch order, so every key is in tune with the patch. OCT − and OCT + shift the keys by a scale period (−3 to +3).

A key is an input into the system, not a note-on. Pressing a key sounds its note directly (with the key's velocity) and pulls the layer's points toward that note over about 0.15 s, so the motion bends around what you play; it lets go when you release. The patch's own envelope shapes the key's note: a sharp Contour gives a struck note (fast rise and fall), a soft one a bowed note (slow rise, long hold, slow release). While the generators run, a held key also breathes with the layer's envelope.

Which layer the keys play is set in Setup → Keys: Layer 1, Layer 2, Both layers, or Drums.

Drum keys (performance key 15, or Keys play → Drums): each key plays one of the four drums (kick, snare, hat, tom, repeating up the keys) at its velocity. The hit rides a note the drum layer is playing, as rhythm hits do.

Latch (performance key 8) holds every key you press until you press it again.

Rolls, styles, locks and undo

A roll makes a new patch from a random seed, shaped by the current style. The same seed and style always give the same patch.

What a roll changes:

• REC (tap) rolls the sound: both voices, both layers, the rhythm and the drums.
• REC (double tap) rolls everything but the scale: the sound, the matrix, the LFOs, the effects and the knobs.
• REC + a page button rolls only that page. REC + SEL is the only roll that changes the scale.
• PRESET rolls everything in the chosen style; ALGO steps through seeds.
• REC (hold) mutates: every continuous setting moves a little from where it is.

Locks. Hold SAVE and press a page button to lock that page: rolls and mutations leave it alone. The header shows LOCKED on a locked page. Lock the scale, a voice you like, or the matrix (SAVE + LFO) and keep rolling the rest.

Undo. Performance key 13 undoes the last roll, mutation or seed change.

Morphs. A roll glides into the new patch (about 1.5 s; 0.3 s in Wild) instead of jumping. Settings that rebuild the map (scale, rotation, root, octaves, surface) cause a short silence of about 15 ms.

Patches and scenes

Patches. 64 slots: four banks (A–D) of 16, one slot per key. SAVE + key stores everything in that slot of the active bank: every setting, the matrix, the knobs' paths and positions, the locks and the four scenes. HOME + key loads it. While SAVE or HOME is held, the keys that hold a patch in the active bank light up. The Perform page shows "patch B5" while a loaded patch is unchanged by rolls. If a patch was the last thing you loaded, it comes back at power-on, with its bank active; otherwise the FM-1 starts on a fresh roll.

The Patches page. A tap on SAVE opens it; another tap goes back to the page you were on (HOME and the page buttons leave it too). It shows the four banks with how many patches each holds, and the active bank's 16 slots: a stored patch lit, the one playing bright.

The bank stays active when you leave the page, so SAVE + key and HOME + key work on it from any page. Storing over a slot that holds a patch replaces it, without asking.

Patches and firmware updates. Updates keep the patches and the settings. 1.0.4 moved the patches into a shared area of the flash to make room for 64: the 16 slots of earlier versions become bank A by themselves at the first power-on. Do not go back to a version before 1.0.4 afterwards: it would miss some patches and forget the Bluetooth speakers, and storing a patch there could overwrite others.

Scenes. Four snapshots inside the current patch, on performance keys 1–4. Hold a scene key for a second to store the current sound; tap it to recall, with a 1.2 s morph. Scenes are saved with the patch.

Settings (theme, key octave, MIDI channel and output, Bluetooth, load caps, keys, the style) are kept with SAVE + OCT+ (hold SAVE first), or K4 on the Patches page. The SAVE button lights while there are changes not kept yet; without keeping them, the next power-on brings back the settings as they were. Storing a patch keeps them too.

Scale (SEL)

Changes to Scale, Rotation, Root, Octaves and Surface take effect when the knob rests (about 0.3 s) and rebuild the map (a moment of silence). Temper retunes without a rebuild.

The 41 scales, in five groups:

• Harmonic: Harmonic series (the ding's partials 1, 2, 3…, not folded into an octave), Odd harmonics, Harmonics 4-8, 6-12, 8-16, Harmonic pentatonic, Undertones 8-16.
• Tongue drum and handpan: Hexany 1-3-5-9, Golden Gate, Celtic minor (Amara), Kurd, Integral, Pygmy, Akebono, Sabye, Aegean, Hijaz.
• Pentatonic and smaller: Fifths, Suspended, Major pentatonic, Minor pentatonic, Egyptian, Septimal pentatonic, In, Kumoi.
• Modes: Major, Dorian, Phrygian, Lydian, Mixolydian, Minor, Harmonic minor, Melodic minor, Acoustic (overtone), Phrygian dominant, Double harmonic.
• Other: Blues, Major hexatonic, Whole tone, Diminished, Chromatic.

Every note is a whole-number ratio of the ding. Notes that hold the key more strongly (the ding, its fifth, its third) have more tonal weight: the motions lean toward them. Low notes far from the ding are kept quieter in the bass, as an arranger would voice them, so low chords stay clear.

Voice 1 and Voice 2 (ENV and GLO)

Voice 1 is layer 1's sound, Voice 2 is layer 2's. Both pages are the same. Every note is up to 16 oscillators at the note's exact harmonics; these settings shape all of them at once, live, and the sound is normalised so they change the colour, not the volume.

A layer plays up to 8 notes at once (Setup → Load). When more want to sound, the quietest fade out over 8 ms; no note is ever cut.

Layer 1 and Layer 2 (EDIT and ARP)

The two layers are the same, except that Path view is on Layer 1's page and moves both.

When a motion's discrete choice changes (a ratio, a figure, the motion itself, the number of points), each point glides from where it is onto the new path over about 0.3 s. A point never jumps.

The twelve motions

The eight envelopes

Every envelope is also accented by the rhythm's stream, by the amount set with Grip (Drums → Lock & motion).

Route: one layer shaping the other

With Route set to anything but Plays, a layer falls silent and acts on the other one instead. Its Energy is the depth. Point j of the played layer takes point j of the shaping layer (wrapping around).

If both layers are set to route, layer 2 shapes and layer 1 plays ("Plays (2 routes)").

Drums and rhythm (SEQ)

The Drums page has 19 tabs. The first ones are the ones you reach for most.

How the rhythm works

The rhythm is a stream: a smooth curve over the bar that peaks at the downbeat, the half bar and the beats, and (depending on the Groove settings) at eighths, sixteenths, triplets or both. It never stops changing smoothly; there is no grid.

• In the Threshold engine, every peak of the stream above a threshold is an event with a strength. Density sets the threshold. Drum choice decides which drum plays each event.
• In the Lock engine, each drum is its own oscillator at a whole-number rate (kick 2 a bar, snare 2 offset by half, hat 8, tom 3), slightly detuned, and Pull couples them back into step: strongly pulled they lock to the grid; loosely, they slip and catch again.

The stream also shapes the synth: Grip accents every envelope with it, and the Stream envelope and Stride motion follow it.

All the drum settings

The drums never change pitch. A hit swells a note that is already sounding and colours it. The kick also lets the note's fundamental through in full (normally partials under 90 Hz are softened), so it has weight. If the drum layer is silent, the hit lands on the note under its loudest point.

With the drums on, the synth sits about 4 dB lower to make room.

Modulation (LFO)

The matrix

The first tab of the LFO page. 24 routes, each a source onto a destination at a depth.

A new route starts at +25 % onto the Timbre knob.

Sources

Sources marked 0 … 1 push one way only from where the destination is set: use a negative depth to pull it down.

Destinations, in this order: the four performance knobs, the LFO rates, Layer 1 (with the path view), Layer 2, Voice 1, Voice 2, the drums, the rhythm, and the effects. Names say where each one is: "Kick decay", "LFO 3 rate", "Layer 2 rate", "Voice 1 tilt". Every continuous setting is there except the master level.

Knobs as destinations

A route onto a knob turns that knob for you, so every setting on its path moves together, exactly as if a hand were turning it. A white tick on the Perform page shows where the matrix has the knob. Your hand still sets the centre the route moves around. Knob sources always read your hand, never the routed position, so knob → knob routes cannot loop. Rolls never route onto the knobs.

Generators as sources

Layer 1 motion and Layer 2 motion let the generators modulate anything: the drums' envelopes, a voice, an effect, a knob. Rolls with the drums on often add one or two Motion → drum routes. Two things to know:

• A layer's motion routed onto its own generator (its rate, energy, reach…) or onto the Motion knob is a feedback loop. It is bounded and stable, but it can settle at an extreme (rate pinned high, say).
• A route onto a knob moves every setting on that knob's path at once.

Rolls and the matrix. Rolling the LFO page (or REC + FX, or a double tap) rewrites the matrix, and mutation nudges its depths. SAVE + LFO locks it so your routes survive both.

LFO 1–6

Effects (FX)

The chain: fuzz → filter → delay and reverb sends → compressor → master → limiter.

After the master, a look-ahead limiter holds peaks at −0.5 dBFS, and a soft clip catches anything that still gets past. Patches come out loud (about −14 dBFS on average) without distorting.

Setup (HOME twice)

From the Perform page, press HOME again for Setup. SAVE + OCT+ keeps these settings.

The load page

The Load tabs show a live profiler: the share of each audio block spent on Control (smoothing, LFOs, the matrix, tables; "of it, gens" is the generators' part), Layer 1, Layer 2 (on core 2) and how long core 1 waited for it, Drums + FX, and the Total. Peak is the worst block, Platform the USB and Bluetooth work, Xruns the blocks that ran out of time, over 90 % the blocks close to it, and voices the current voice cap.

If the audio ever runs out of time, MANIFOLD drops a voice at once (a thinner chord, never a click) and gives voices back one every 4 s while it keeps up. "OVER n" in the Perform page's header counts these moments.

MIDI

MANIFOLD is a USB MIDI device, and a Bluetooth MIDI device.

In (on the MIDI channel set in Setup, or any channel at Omni):

Out (with Keys to MIDI out on): the keys send note on / off on channel 1, each as its nearest equal-tempered note, over USB and Bluetooth MIDI. The generators do not send MIDI. MANIFOLD does not send or follow MIDI clock.

Bluetooth audio

MANIFOLD can send its audio to Bluetooth headphones and speakers. It cannot receive audio.

1. Press HOME twice for Setup, then SELECT to Bluetooth audio.
2. K1 turns Bluetooth on.
3. Put the speaker or headphones in pairing mode and press REC to scan (about 10 s).
4. K2 picks the device.
5. Turn K3 right to connect (left to hang up).
6. K4 sets whether the last device is called again at power-on.

Four devices are remembered. While it streams, the FM-1's own output is muted and the header shows BT. Bluetooth audio arrives 150–300 ms late (the receiver's buffer), so it suits listening more than playing in time.

The FM-1 sends SBC at 44.1 kHz, joint stereo. It works both with devices that wait for the source to set up the stream and with those that set it up themselves after pairing (most speakers do; 1.0 refused those). If a device will not connect, put it back in pairing mode, connect again, then open the web installer's Read the crash report straight away: it lists each step of the Bluetooth set-up and whether the FM-1 or the device turned it down.

Recipes

A slow ambient bed. PRESET → Ambient. On Layer 1: Motion Drift or Gravity, Envelope Swell at 1 per 4 bars, Contour low. Drums off (performance key 12). FX: Reverb decay 20 s, Reverb tuned On. Turn Space up.

A pulse that plays the scale. Layer 1: Motion Ladder (Span 8, up and down), Rate 1 a bar, Envelope Pulse at 2 a beat, Contour high. Layer 2: Route Multiplies, Envelope Stream: the run is gated by the rhythm.

Drums from the melody. Drums → Follow: set the hat to Layer 2, Place to point 1. The hat now fires when layer 2's first point swells. Set layer 2's Route to Adds so it shapes layer 1 silently while it drives the hat.

The melody makes the groove. Drums → Lock & motion: Motion up. As layer 1 moves across the map, the rhythm gets busier on one side and sparser on the other.

A generator turns a knob. LFO page, Matrix: Source Layer 2 motion, Destination Space knob, Depth +40 %. Layer 2's swells now open the reverb and delay. Lock the matrix with SAVE + LFO.

Long-form evolution. Drums → Rhythm: Form high. Drums → Lock & motion: Evolve around 30 %. Leave it running.

Play along with other instruments. Scale → Temper: Equal (12-tone). Root to match the song.

Troubleshooting

No sound. Press PLAY (the generators start stopped). Check Master (FX → Output) and the layer levels. Check the performance-key mutes (hold PLAY: L1, L2, GEN on the Perform page should be lit). If BT shows in the header, the sound is going to Bluetooth.

A key does nothing. Setup → Keys: is it set to Drums, or to a muted layer? Latch may be holding the key: press it again, or performance key 14 (Panic).

It stopped changing when I roll. A page may be locked: LOCKED shows in its header. SAVE + its button unlocks it.

"OVER" in the header. The audio ran out of time and a voice was dropped. Lower Setup → Load (voices, partials) for very dense patches.

The scale did not change on a roll. Only REC + SEL rolls the scale.

A Bluetooth speaker says connected but plays nothing, or the screen says REFUSED. Update to 1.0.2 or later (1.0 refused speakers that set up the stream themselves). Then see Bluetooth audio for reading the set-up's log.

Saved patches or settings are gone after power-off. FM-1s sold since autumn 2026 carry a different flash chip (UC25HQ80). MANIFOLD before 1.0.3 did not recognise it and kept everything in memory only. Install 1.0.3 or later.

The battery gauge. It reads the battery once at power-on and then every 10 s (in a slot of the key scan that no key uses, so playing is never affected), averaged over about 40 s. On USB power it shows USB.

For developers

MANIFOLD is open source (MPL-2.0) and builds on fm1-base. This part describes the engine's mathematics and the code's organisation.

Building

git clone https://github.com/stets43/Manifold
git clone --recursive https://github.com/charlesvestal/fm1-base
cd fm1-base
git checkout 2d8ed74 && (cd bsp && git checkout 773b0b9)
git apply ../Manifold/patches/fm1-base.patch
(cd bsp && git apply ../../Manifold/patches/felucca-bsp.patch)
python3 tools/build.py ../Manifold --host        # the host simulator: any Linux or macOS
../Manifold/build/host/manifold_host ../Manifold/tests/basic.txt ../Manifold/build/host
tools/get_toolchain.sh                           # JieLi's clang for pi32v2
export JIELI_TOOLCHAIN=~/.jieli/toolchain AC79_SDK=/path/to/fw-AC79_AIoT_SDK
python3 tools/build.py ../Manifold --release 1.0.4 # -> build/manifold-1.0.4.fwsc

MANIFOLD needs a few changes to fm1-base (a larger RAM code window for its control tick, the battery read in the key scan's pot slot, Bluetooth audio's acceptor role, both flash chips, and the store's APP_STORE_POOL_FOREIGN); they are in patches/, against the fm1-base and felucca-bsp commits above.

The store. The 64 patch slots and the Bluetooth record share fm1-base's pool (APP_STORE_POOL, app.h): 69 sectors from 0x97000, one copy per sector, the newest valid copy of an object winning, so a power cut during a save leaves the previous copy. 1.0's 16 slot pairs sat at the pool's first 32 sectors and are read as pool copies as they are; the Bluetooth record's pair at 0xDE000 moves in at the first boot. A slot's current copy that is not a MANIFOLD patch (another firmware's record of the same format) is erased at boot. A patch is 3052 bytes.

The device build needs three files from JieLi's AC79 SDK (cpu/wl82/tools/uboot.boot, cfg_tool.bin, cfg/eq_cfg_hw.bin; Apache-2.0). tests/basic.txt is the host test suite (144 checks: every page, rolls, locks, the performance keys, scenes, undo, patches, MIDI, the matrix, the profiler). hosttest/render.c is a desktop render harness (single patches, sweeps, a tour).

Architecture

The audio runs at 44.1 kHz in blocks; everything that is not per-sample runs in a control tick every 64 samples (1.45 ms): parameter smoothing, the LFOs, the matrix, the rhythm, both generators, the drums' envelopes and the voices' spectra. Layer 2's voices run on the FM-1's second core while core 1 renders layer 1. The UI talks to the engine only through a lock-free command queue drained at the start of each audio block.

Parameters are stored normalised (0…1) in target (what is set), base (smoothed toward it) and mod (base plus the matrix and the knobs' paths, recomputed each tick). Structural parameters (scale, rotation, root, octaves, surface) rebuild the engine in the main loop. Code that runs in the audio interrupt is placed in RAM (DSP_CTL, DSP_INL); the rest runs from flash (DSP_FAR calls). The audio path never allocates and never calls into flash.

The drive: from points to loudness

Each layer has points j = 1…n at positions qⱼ(t) with envelopes *e*ⱼ(t). Each note i sits at pᵢ on the surface with tonal weight *w*ᵢ. The note's drive is

u_i(t) = w_i · Σ_j  A · e_j(t) · g(t) · φ(|q_j(t) − p_i|)

φ(d) = (1 − (d/R)²)²  for d < R,  else 0          R = s · (0.6 + 1.2 · Reach)

where s is the layout's mean spacing between notes of different pitch classes, A = 0.35 + 0.65·Energy and g(t) the stream's accent: g = (1 − γ) + γ · clamp(0.25 + 1.5 R̂(τ), 0, 1), γ = 0.7·Grip. φ is a smooth bump with a continuous slope that is exactly zero beyond R, so the drive is C¹ in the points' positions. Distances are on the surface: Euclidean on the plane, wrapped on the torus, chordal on the sphere. The keys add their own input: *u*ᵢ += *k*ᵢ(t). Loudness is the drive through a 3 ms symmetric smoother.

Point j's phase along the motion is t·Rate + Spread·j/n, with Rate snapped to the nearest of 1/64 … 4 cycles a bar (whole-number ratios). Motions output (x, y) in [−0.45, 0.45]² and a third coordinate h ∈ [0, 1]. The path view maps them onto the surface:

X = c_x + o_x + k · (x cos θ − y sin θ),    Y = c_y + o_y + k · (x sin θ + y cos θ),    k = (f / 0.45) · scale

with (*c*ₓ, *c*ᵧ) and f the centre and half-extent of the notes' frame (so scale 1 covers every note), θ the path rotation and o the path offset. The plane folds at its edges, the torus wraps, and on the sphere crossing a pole flips longitude by half a turn, so every path stays continuous.

When a motion's discrete choice changes, the point's offset from the new path decays with a 0.1 s time constant: the position is always continuous.

The motions

Below, t is the point's phase in cycles, sn(z) = sin 2π*z*, cs(z) = cos 2π*z*, and A, B ∈ [0, 1] the two controls.

Orbit (Lissajous). With ρ chosen from {1, 2, 3/2, 4/3, 5/4, 5/3, 3, 5/2} by A:

x = 0.45 sn(t),   y = 0.45 sn(ρt + B/4),   h = ½ + ½ sn(ρt/2)

Ladder. The notes sorted by pitch; a window of M = 3 + round(9A) notes, each point starting two notes higher. The position along the run is u = φM (up), (1 − |2φ − 1|)(M − 1) (up and down) or (1 − φ)M (down), φ = t mod 1. Between note i and i+1 the point rests and then moves: f = smoothstep((frac(u) − 0.55)/0.45).

Swarm (Kuramoto). Each point j has a phase θⱼ on a circle of radius 0.2 + 0.25 j/(n − 1):

dθ_j/dt = ω_j + K (Im(Z) cos 2πθ_j − Re(Z) sin 2πθ_j),   Z = (1/n) Σ_q e^{2πiθ_q}
K = 3A,   ω_j = 1 + B/2 · ξ_j  (ξ_j ∈ [−1, 1] fixed per point),   h = |Z|

Above a critical coupling the phases lock (the points gather into a chord); below it they scatter.

Lorenz. Integrated with Heun's method (RK2), steps ≤ 0.004:

ẋ = 10(y − x),   ẏ = x(ρ − z) − y,   ż = xy − (8/3)z,   ρ = 20 + 30A
position = (x, z − ρ + 1) / (35 + 30(1 − B)),   h = z / 1.6ρ

Motif. A small Lissajous figure of ratio r (from A) around a centre that moves each quarter cycle through home, home, answer, home (A A B A). "Home" is the ding, the "answer" the next strongest note of the key (its fifth), the third, or alternating (B). The centre glides over the last 15 % of each quarter.

Drift (value noise). Two octaves of hashed random knots joined by the quintic w = 6f⁵ − 15f⁴ + 10f³, at 1 + 3B knots a cycle, the second octave three times denser at amplitude 0.6A:

x = 0.9/(1 + 0.6A) · Σ_o a_o [ (1 − w) N(n) + w N(n + 1) − ½ ]

Billiard (Sinai). A point moves in straight lines at constant speed in the box |x|, |y| ≤ 0.45, reflecting off the walls and off a central circular bumper of radius 0.28B (mirroring the velocity in the bumper's tangent). The heading turns with changes of A. Without the bumper the paths close into figures; with it the billiard is chaotic.

Gravity. Up to three wells at the key's strongest notes (the ding, then its fifth, then its third: W = 1…3 from A), each of mass GM = 0.25/W, softened by ε² = 0.0064:

a = −Σ_k GM (q − w_k) / (|q − w_k|² + ε²)^{3/2}

integrated with symplectic Euler (steps ≤ 0.01). To keep the orbit bounded without damping it, the speed is eased toward the value the target energy E = −GM·W·(0.8 + 3(1 − B)) asks for at the current potential: v² → 2(E − Φ), by at most 10 % a step. h is the speed.

Stride. A heading θ and a speed v = R̂^{3/2}·(2 + 8B), with R̂ the rhythm's normalised stream: the point moves only as the stream peaks, and turns while it rests: dθ = (A − ½)·3·(1 − R̂)·dt. Walls reflect.

Loops. Point j sits on its own note of the key (the strongest 2 + round(4A), each in its own octave) and swells once per loop of length Lⱼ ∈ {5, 7, 8, 11, 13, 17, 19, 23} quarter cycles:

ψ_j = frac(4t / L_j + 0.37 j),   e_j = ½ − ½ cos(2π ψ_j / w)  for ψ_j < w,  w = 0.12 + 0.5B

The lengths are pairwise coprime, so the whole pattern returns only after their product.

Erode. A six-note figure (scale steps 0, 2, 4, 3, 5, 1 from a low note) repeated every cycle. Over a life of 4·2^{4A} cycles a wear level rises to 0.25 + 0.75B and then renews over the last tenth. Each note i fades when the wear passes its threshold (0.95, 0.35, 0.6, 0.15, 0.8, 0.5), so the weakest notes go first.

Chords. Four chords a cycle from a progression (A): I IV V I, I VI IV V, I III IV II, I V VI IV, I I IV I, I VII VI V. Point j holds the chord's root + j × 2, 3 or 4 scale steps (B: thirds, fourths, fifths), from an octave and a half above the ding, gliding to the next chord over the last 20 % of each quarter.

The envelopes

Each point's envelope eⱼ(t) ∈ [0, 1] (Adds may reach 1.2), with Contour C ∈ [0, 1]:

S is smoothstep; c ramps from 0 to 1 over the first second (the running averages need data). For Pulse and Swell, ψ is the envelope's phase at Envelope rate ν (cycles a beat, times 4 beats a bar), plus the point's Spread offset. It is phase-locked to the bar: dψ/dt = ν/bar + 2·err, err the wrapped difference from ν·(bar position), so after a tempo change it eases back into step within about half a second.

Routes, with depth d = the shaping layer's Energy and m its point j mod n: Moves qⱼ += d·qₘ; Adds eⱼ += d·eₘ; Multiplies eⱼ ← eⱼ·(1 − d + d·eₘ).

Keys. A key press is a kernel in time: a smoothstep rise over a = 2 ms + 1.2(1 − C)³ s, then an exponential fall with time constant 0.12 + 3(1 − C)² s; a held key adds a sustained level (0.25 + 0.65(1 − C))·velocity that breathes with the layer's envelope while it runs. Each key also pulls every point of its layer toward its note: the offset approaches Σ kᵢ Δᵢ / (1 + Σ kᵢ) with a 0.15 s time constant (Δᵢ the way to note i on the surface).

The rhythm

The stream is a sum of von Mises bumps over the bar position τ ∈ [0, 1):

R(τ) = (1/W) Σ_k w_k · b(n_k τ − φ_k),     b(z) = exp(5 (cos 2πz − 1)),    W = Σ w_k

with harmonics nₖ = 1, 2, 4 (always), 8, 16, 32 (the twos), 3, 6, 12, 24, 18 (the threes) and an off-beat at 4. Threes crossfades the two families; Fine opens 8/3, 16/6/12, 32/24 in turn; Swing moves the off-beat's phase from ½ through ⅔ (triplet swing) to ¾ while the straight 8, 16, 32 give way to 12 and 24; Turn shifts the threes by up to ⅓ bar. Form adds slow cosines (periods 3, 4, 5, 8, 16, 64 bars) to the threshold, the sixteenths' weight, the three-feel and the selector.

Events (Threshold engine) are local maxima of R above the threshold θ = 0.03 + 0.6(1 − Density)², refined by a parabola through three ticks so they land on the right sample. An event's strength is (peak − θ)/(1 − θ).

Select scores each drum d for an event of strength s: score = 1 − 1.6|s − (1 − Place)| + polarity·selector + (density − ½)·0.8 − Feedback·tired, with the kick taking the strongest events (s > 0.8) as an anchor. Count distributes events by their order.

Lock: four phase oscillators θ_d with rates r_d (kick 2, snare 2 offset ½, hat 8, tom 3 a bar, varying with Density, Fine and Threes) and small detunings δ_d:

dθ_d/dx = r_d (1 + δ_d) + K r_d sin 2π(r_d x − θ_d),    K = 0.4 Pull

Above its detuning a drum locks to its exact rate; below, it slips and catches. Each hit nudges the others.

The drums

A drum's envelope after a hit: a linear rise from its current level over Attack, a hold, then a decay over Decay,

env(t) = ex + Curve · (lin − ex),   ex = 2^{−5.77 t/Decay}  (−35 dB at Decay),   lin = max(0, 1 − t/Decay)

so Curve blends exponential and straight. It is recomputed each tick from the current parameters, so modulation reshapes a hit that is still ringing. The hit rides a sounding note on the drum layer (Voice picks lowest … highest), raising that note's level by the envelope (its own gain, independent of the layer's level staging) and, in proportion to its share of the note's level, tilting the partials (Bright, up to +2.7 dB per partial, settling over 300 … 9 ms) and pushing Wave (Snap, 25 ms). The kick's duck multiplies the other voices by 1 − 0.75·Duck·env², released over 150 ms. No drum ever changes a frequency.

The voices

Each note f is a bank of oscillators at k·f, k = 1…16 (and up to 64 for low notes, from shared tail tables). The level of partial k is one function, normalised to unit energy:

a_k ∝ k^{−1.6 + 1.2·Tilt} · (1 + g · exp(−(k − c)² / 2b²)) · comb(k) · tone(k f) · bloom(k)
c = 2 + 10·Center^1.6,   b = 0.5 + 7·Band,   g = 2·clamp((c − 2)/3, 0, 1)   (a lift of up to +9.5 dB)
comb(k) = (½ + ½ cos(2π (k − 1) / stride))²,   stride = 1 + 3·Stride
tone(F) = 1 / (1 + (F / f_c)⁴)  (−24 dB/oct),   f_c = 250 · 2^{6·Tone} Hz
bloom(k) = (2^{−0.36·Bloom·(1 − loudness)})^{k − 1}

Partials 7, 11, 13 and 14, which belong to no scale but the harmonic series, are held back. Phases follow φₖ = π·D·k², D = Phase/8 (Schroeder's low-crest-factor phases at D = 1/16, Phase = 50 %). Partials below 90 Hz are softened (12 dB/oct), with the level made up from the partials above, so bass notes read on small speakers and leave the sub to the kick. Wave adds each oscillator's own 2nd and 3rd harmonics (0.5 sin 2x + 0.33 sin 3x); Detune doubles partials 1–3 with copies up to 14 cents away. No partial above 0.45·*f*ₛ is played.

The oscillator budget is 64 per layer. When a layer needs more, a floor rises (from −44 dB relative to each note) so the quietest partials fade first, over a one-octave knee; whole notes are never cut.

The map

Each scale degree n/d is factored into exponents (e₃, e₅, e₇) of 3, 5 and 7 and placed at

x = e₃ + 0.5 e₅ + 0.45 e₇,     y = 0.866 e₅ − 0.78 e₇

(fifths along x, major thirds at 60°, natural sevenths at −60°; 11, 13 and higher primes of the harmonic series each get a direction of their own). Each octave of a degree is offset by a small step at the golden angle, so registers spread without breaking the lattice. The plane scales the lattice into [0.1, 0.9]²; the torus wraps it (fifths one way, thirds the other); the sphere uses a Fibonacci layout with low pitches to the south.

A note's tonal weight is its harmonicity to the ding (Tenney height: 1.15 − 0.1 log₂(nd), from 1 down to 0.45), times a bass-voicing factor: an interval over the ding is clear only above a frequency limit that rises as the interval gets more complex (about 58 Hz for a fifth, 100 Hz for a major third, 150 Hz for a second).

Effects

Fuzz: two cascaded gain stages into slightly asymmetric soft clippers with band-limiting between them, and a tone blend from a 500 Hz low-pass to a 1.4 kHz high-pass. Filter: one resonant state-variable filter, its low, band and high outputs crossfaded by Filter type. Delay: a bucket-brigade-style line whose write rate sets the time. Reverb: an 8-line feedback delay network at half the sample rate (mutually prime lengths of 34–99 ms scaled by Size, four of them modulated), with allpass diffusion; Tuned snaps each line to a whole number of periods of a scale note. Compressor: a bus compressor with parallel mix; Pump ducks it on layer 1's onsets. Limiter: peak detection over eight 8-sample segments 64 samples ahead, a 7-sample attack and ~280 ms release, ceiling −0.5 dBFS; then a soft clip.

Licence and credits

MANIFOLD is MPL-2.0. It is built on fm1-base by Charles Vestal (MPL-2.0), which includes code by Leo Kuroshita (Felucca), Chris Farrell and others; see fm1-base's LICENSING.md. A firmware built with fm1-base's own Bluetooth stack also contains Apache-2.0 and BSD-2-Clause code (an SBC encoder, micro-ecc, JieLi radio tables): their licence texts ship with the firmware.