Grid mode

This is the main MLRws performance interface: six tracks of looping audio, all driven from a monome or DIY grid / midigrid.

Everything here works the same whether the grid is plugged straight into the Computer (USB host) or reaches it through a norns running gridproxy (USB device). The README covers setting up each one.

Hardware in and out

In grid mode the interface on the Computer itself is intentionally minimal. Tracks are recorded as mono ADPCM, and each one can be panned anywhere between Audio Out 1 and Audio Out 2 and run through its own low-pass filter. Knob X is the input gain and the monitor level while armed/recording. Knob Main is the master output volume.

Audio In 1 / Audio In 2 are the record sources: which input is captured into a track is set by that track's input selection on the REC page (or auto-picked from whichever single input is plugged in if you haven't chosen).

CV In 1 / CV In 2 modulate pan and the filter cutoff (or rotation) of chosen tracks (see CV inputs below).

Pulse In 1 / Pulse In 2 act as transport-style triggers (see Pulse inputs below).

CV and pulse outputs are driven by output-enabled cut/gate activity (manual taps on the CUT page, pattern playback that replays cut press/release timing, and recall playback that replays cuts):

• CV Out 1: chromatic note (sample-and-hold). Output-enabled CUT keys map to pitch chromatically left-to-right, with adjacent rows tuned like guitar strings: mostly perfect fourths, with a major-third break between track rows 3 and 2. On 16-row grids the bottom half repeats the same pitch map as the top half. Knob X adds a continuous ±24-semitone (~±2 V) offset on top of the held note.
• CV Out 2: ASR envelope that attacks from its current value to roughly +5 V when an output-enabled CUT key is pressed, sustains while the key/gate is held, and releases back toward the resting −1 V floor when the gate drops. Knob Y sets the release time when the gate releases (10 ms at fully left, ~3 s at fully right). Hold the front-panel switch Down with no track armed or recording, then move Knob Y to set attack time (instant to ~1 s).
• Pulse Out 1: 20 ms trigger fired by output-enabled CUT-page track-row keys, including taps on empty track rows
• Pulse Out 2: gate. High while any output-enabled CUT-page track-row key is held, including held keys on empty track rows, or while an output-enabled gate-mode track is playing

For populated tracks, CV1 pitch updates, CV2 envelope gates, Pulse Out 1 triggers, and Pulse Out 2 gates are disabled by default and can be enabled per track with the sample-manager web app's CV output toggle. Empty tracks always drive CV/pulse outputs so they can be used as pitch/envelope/gate rows before audio is loaded.

CV inputs

Both CV inputs act on the last-touched track (the last track row you pressed on the CUT or REC page) unless you choose otherwise. In the sample-manager web app you can tick any set of tracks for each input instead, to modulate several tracks at once.

• CV In 1: pan offset. Shifts the target tracks' pan away from where you set it on the grid: 5 V covers the full width (12 pan steps), so 0 to +5 V sweeps a hard-left track all the way right and −5 to 0 V sweeps a hard-right track all the way left. It's clamped at the edges.
• CV In 2: filter cutoff (the default) or rotation, chosen in the web app:
  • Filter cutoff: 0 V (or below) is the darkest setting and +5 V is fully open, continuously and with no glide. While CV In 2 is plugged in, the filter keys are ignored on its target tracks.
  • Rotation: turns the target tracks' whole recording. The playhead still wraps to the first column (or the loop start), but "the start" of the audio moves by a share of the track length, so a loop scrubs through the material. 0 V is normal and +5 V turns it by the range set in the web app (100% is almost a full turn). New rotations land at the next wrap or cut.

When a track stops being a target, or you unplug the cable, the track keeps the last value the CV gave it. Hold DELETE for 5 seconds (see Delete) to put them all back. CV moves are live only: they aren't recorded into patterns or saved.

Pulse inputs

Both pulse-in jacks act as transport-style triggers in grid mode:

• Pulse In 1: loop reset. A rising edge resets the playhead of every track that is currently playing and has an active CUT-page loop, jumping each one to the loop's start column. The loop remains active; only the playhead jumps. Tracks without an active loop, and stopped tracks, are unaffected. (Matches gridless mode, where Pulse In 1 is also the reset trigger.)
• Pulse In 2: gated record. While a track is armed via the REC page, holding Pulse In 2 high records into that track for as long as the gate is high. Recording starts on the rising edge and stops on the falling edge. The usual record gates still apply (a track must be armed, recording must not already be in progress, and the per-recording sample limit must not have been reached). While pulse-gated recording is active, the front-panel switch will not interrupt it. Recording automatically stops if the time limit is reached.

Pulse Out 1 and Pulse Out 2 follow output-enabled cut/gate activity as described in Hardware in / out above.

Track layout

Central to the grid layout on both pages is that the middle six rows of the grid are organized into horizontal tracks, one row per track for tracks 1–6 (top to bottom). The top row is reserved for navigation/patterns/recalls and the bottom row is the master-volume gradient bar.

The top and bottom keys

The keys at each of the four grid edges have common functionality no matter which page you are on in MLRws.

Page selection

The two grid keys at the top left of the grid control which page is selected between page 1: CUT and page 2: REC.

Pattern looper

Patterns are timed motion recorders. They capture every grid-based event you generate (cuts, loops, speed changes, reverse toggles, volume, pan and filter changes, master moves, even other patterns/recalls firing) and play them back in a free-running loop.

CUT-page key releases are recorded too, so output-enabled pattern playback recreates both the Pulse Out 2 gate length and the CV2 ASR envelope sustain. On 16-row grids, the bottom-half keyboard layer is recorded into patterns as CV/pulse gestures as well, without affecting audio track playback. Overlapping keys are treated monophonically per row/layer: a newer press replaces the previous held key without dropping the gate.

You interact with patterns using the group of 4 dim LEDs to the right of page selection in the top row. A dim pattern slot indicates an empty one. press an empty pattern slot to arm the looper. Your next grid gesture starts the recording and recording continues until you press the recording pattern button again, at which point loop playback starts immediately.

Once recorded, pattern playback can be toggled on/off in the patter looper area of the grid. To record a fresh pattern over an existing one, first clear the old one by holding the DELETE key and then touching the pattern you want to overwrite, which will clear it.

Multiple patterns can play simultaneously. Each pattern's loop length is determined by the time between record-start and record-stop, so you can layer different-length loops.

Recall

Recalls are instant snapshots of every track's state (current cut position, loop region, speed, reverse, volume, pan, filter, gate flags). They have no timing: pressing a recall instantly places all tracks into the snapshot state.

Recall are controlled by using the second group of 4 dim LEDs to the right of the pattern looper in the top row. Touch an empty recall slot to capture the current configuration as a recall. Recall a captured recall from any other grid state by touching the corresponding recall key. Note that when you are in a grid state that does not correspond to any recorded recall and you switch to a recall with the recall keys, pressing the same recall key will switch you back to your previous state without having to capture that state- so you can easily have momentary switches to recalls without losing progress.

Recalls are themselves recorded into patterns, so you can build a pattern that triggers different recalls at different times.

Overwriting a recall requires that you clear the old one by holding the delete key then pressing the recall key that you want to clear.

Delete

The delete key is used to clear data from various places in MLRws. Hold it down and then press a pattern or recall to clear it. Hold it down and press the record-arm button for any track with audio on it and that audio will be cleared.

Hold the delete key by itself for 5 seconds to reset the current REC page parameters to defaults. The delete key flashes three times quickly to confirm. This resets current speed, reverse, loop, mixer level, gate mode, track groups, and active recall state, puts every track's pan back hard to its input side, opens every filter, and clears held CV pan offsets and rotations, then saves those defaults to flash. Currently playing patterns are stopped so they do not immediately re-apply old automation. It does not reset master volume, or delete audio, patterns, or saved recall slots.

Saving

MLRws saves your settings to the card by itself, so they come back after a power cycle: speed, reverse, loops, levels, pan, filter, gate modes and the master level are written to flash within about 4 seconds of a change, and patterns, recalls and groups are saved as soon as you record, capture or clear them. Recorded audio is written to flash when the recording finishes.

Grid-based main volume control

The bottom row on the grid is used to represent the main volume (also controlled by the Main knob on the Computer). Volume control is "last-write-wins" so updating main volume via grid will take precedence over the main knob control until the main knob's next change.

CUT page: playhead cutting and loop-a-section

The CUT page is the performance heart of MLR. Each track row is a scrub bar that spans the full width of the grid (16 cells on a 16-wide grid, 8 cells on an 8x8). The grid column you tap maps proportionally to a position in that track's audio.

• Tap any column on the row: jump the playhead to that position and (re-)start the track. The bright cell tracks the playhead in real time.
• Hold 2+ keys on a row: define a loop region between the lowest and highest held keys. The loop region stays dimly lit while looping. Releasing all keys leaves the loop in place.
• Tap a single key inside or outside an active loop: clears the loop and cuts to that position.
• Delete + any cut key on a row: if the track is playing, stop it (the loop, if any, is left in place so a second Delete + key clears it). If the track is already stopped and has a loop, that press clears the loop instead.

Output-enabled CUT keys update CV1, gate the CV2 ASR envelope, trigger Pulse Out 1, and hold Pulse Out 2 high while held. Empty track rows are always output-enabled and act as chromatic CV keyboards. Pitch runs left-to-right by semitone with guitar-like row tuning. Empty top-half rows show a dim major scale guide with brighter root notes while active or lingering; populated rows never show the guide. On 16-row grids, lower-half rows 9-14 provide the same CV/pulse keyboard and always-visible guide; the bottom corner keys, pressed simultaneously, toggles that guide.

REC page: input, pan, mixer, reverse, filter, and speed

The REC page (page 2) is the per-track parameter editor. We will break this page into parts for simplicity below.

Record arm and input

On all grids, col 0 arms a track for recording. On 16-wide grids, cols 0 and 1 both arm, and also choose which input the track records from: col 0 = Audio In 1, col 1 = Audio In 2. While a track is armed or actively recording, the selected input's LED carries the record-arm flash.

When a track isn't armed, the two keys show its pan instead: key 1 alone is hard to Audio Out 1, key 2 alone is hard to Audio Out 2, and both at half brightness is centre. The display includes any CV In 1 offset, so you can watch it move.

If you have not manually picked an input for a track, MLRws will auto-select the plugged input when exactly one of Audio In 1 or Audio In 2 is connected. With both or neither connected, it keeps the track's previous input. A new recording starts hard to its input's side.

More details in Recording

Pan

On 16-wide grids each track can sit anywhere between Audio Out 1 and Audio Out 2, using an equal-power pan law (13 positions, from hard Out 1 through centre to hard Out 2).

• Pan mode: with the switch in the middle and nothing armed or recording, hold both keys in cols 0 and 1 on a track row. The rest of that row turns into a pan display: cols 2–7 are the six steps toward Out 1, cols 8 and 9 together are centre, and cols 10–15 are the six steps toward Out 2. Press a key to move the pan there. Release either arm key to leave pan mode (it doesn't arm or record).
• Hop: when a track is panned hard to one side, a single press on the other side's key (col 0 or col 1) hops it across to the opposite side, without arming and without interrupting playback. Pressing the key on the side it's already on arms as usual.
• Glide: on a playing track, pan moves glide at 100 ms per step, so a full hop takes about 1.2 seconds. Stopped tracks jump straight there.

Pan is saved, recorded into patterns, and captured by recalls. CV In 1 can offset it.

Mixer

Five discrete level slots. From left to right they are about +3 dB, unity (the default), -6 dB, -12 dB, and silent.

While a track is actively recording, the mixer area turns into a record-progress bar instead of a mixer, indicating how much recording time remains at the current recording speed.

Reverse

Tap to flip playback direction. LED is bright when reverse is on. On 16-wide grids, holding the reverse key instead shows and sets the track's filter; a quick tap (under about 0.3 s, with no filter key pressed) is still a reverse toggle.

Filter

On 16-wide grids every track has its own 4-pole low-pass filter, modelled on the classic Moog ladder with a gentle fixed resonance (a slight lift just below the cutoff).

• Hold the reverse key (col 7) on a track row. The mixer keys (cols 2–6) on that row turn into the filter: from left to right 250 Hz, 600 Hz, 1.5 kHz, 4 kHz, and open (no filtering). The bright key shows the current cutoff, sliding between keys as it moves.
• While holding, press one of those keys to set the cutoff. Release the reverse key and the mixer keys go back to setting the level.
• Glide: on a playing track the cutoff glides at 500 ms per key, so a sweep from the darkest setting to open takes about 2 seconds. Stopped tracks jump straight there.
• You can hold the reverse keys on several rows at once to watch or set several filters together.

The filter is saved, recorded into patterns, and captured by recalls. With CV In 2 in filter mode, the CV sets the cutoff of its target tracks directly and their filter keys are ignored while it's plugged in.

Speed

Seven discrete pitch slots, symmetric around 1× speed. From the left, with the corresponding music interval you will hear based on a track recorded at 1x speed, the options are:

• 1/4x speed (-2 oct)
• 1/2x speed (−1 oct)
• 2/3x speed (−5th)
• 1×
• 3/2x speed (+5th)
• 2x speed (+1 oct)
• 4x speed (+2 oct)

Note that these intervals change depending on what speed you originally recorded the track.

Playback toggle and gated playback

The right most grid column on the REC page controls the playback state of each track. Short press any key in the this column and the corresponding track playback is toggled on/off. Long press one of these and the playback key will flash, indicating "gated playback" mode. In this mode, playback will only occur while a key in the CUT page is held down. Very useful for percussive sounds and very fun to record with the pattern looper.

Gate mode is per-track, so you can have some rows in gate mode and others in normal playback mode. Gate-mode state is saved alongside the recall, so each track returns to its last gated/normal setting after a power cycle.

Track groups

Multiple tracks can be linked into a group so that play/pause behaves as a single choke voice across every member.

• Create a group: hold two or more populated play keys (right-most column) at the same time. Tracks without recorded audio are ignored for grouping. As soon as a second populated play key joins, MLRws cancels the pending gated-playback long-press timer on every held key, so none of them will accidentally enter gated playback. When you start releasing the keys, the first release commits the group: every populated play key that was simultaneously held at that moment becomes a group, and their play LEDs flash rapidly to confirm. (The remaining held keys' releases are absorbed silently.) Hold just one play key by itself and the original long-press → gated-playback behaviour is unchanged.
• Dissolve a group: hold the DELETE key (row 0 ALT). While DELETE is held, MLRws cycles through every existing group, fast-blinking each group's play keys in turn. Each group flashes twice before moving to the next one so you can see which tracks belong to which group. Touch any key on any member row to dissolve that group; the former members' play LEDs blink twice quickly to confirm.
• Choke playback: a group can host at most one playing member at a time. Tapping a stopped member starts it and chokes any sibling that was playing (the playing member stops instantly). Tapping the playing member stops the whole group.
• Persistence: groups survive a power cycle and are saved to the recall blob when created or dissolved.

Recording

Recording is speed-linked up to 1×. Slower settings on the REC page become the record rate, so half-speed recording captures twice as many seconds of maximum audio length and trades quality for more time. The slower the recording speed, the more noise and distortion will be introduced. Settings above 1× are playback-only; recording is capped at 1×.

While a track is armed or recording, Knob X controls how loud the input is recorded. The same level is applied to the monitor mix so what you hear matches what you'll capture. The track level from the grid mixer is applied to monitoring and playback, but recording captures the input using only the input gain.

When the maximum recording length is reached the track auto-stops.

The card writes the new audio to flash after the switch returns to middle- and recordings are therefore persisted on the card itself.

There are two ways to record:

Armed recording

1. On the REC page, while the switch is at Middle, tap col 0 on the desired track row. The arm LED starts a slow flash. Any track that was playing on that row stops so you do not record over itself, and input monitoring is enabled.
2. Move the switch Up or Down. Recording starts immediately, the arm LED goes to a fast blink, and the mixer area (REC page) or cols 1–14 (CUT page) become a progress bar. You can also trigger an armed recording by sending a gate high signal to pulse input 2.
3. Return the switch to Middle to stop. The track is automatically disarmed and playback starts immediately. Other tracks that were already playing keep playing while you record.

Quick recording

If no track is armed and the switch is already Up or Down, go to the REC page and press and hold col 0 on a track row. Recording runs for as long as you hold the key (or until the switch returns to middle, or the track fills up). This is the fastest way to grab a quick stab.

Gridless mode

Gridless mode is what MLRws falls back to when the Computer powers up as a USB device and nothing on the other end is talking to it (no grid, no sample manager). The whole six-track instrument is driven from the Computer's own panel: switch, three knobs, CV/Audio/Pulse jacks, and the six LEDs.

At a glance

• Every track that already has audio on it plays and loops continuously. There is no start/stop. The panel only changes which track is "active" and how everything sounds.
• One track is always the active track. The panel's knobs and switch shape that track's playback (or, in global mode, shape the mix around it).
• The Main knob on the Computer is used to select the active track.
• The X knob sets the level of the current active track (this only ever applies to the current active track).
• The Y knob is an RxMx style "radiate" control that set the level of tracks adjacent to the active track. Y at 0 means only the active track plays (Radio Music style). Y at full means all tracks play at the level set by the X knob.
• Audio Out 1 and Audio Out 2 are both active as a stereo pair. Each track plays at the pan last set for it in grid mode or the sample manager. A track that was never panned sits hard on the side of the input it was recorded from (see Recording below).

Two switch positions, two roles for the knobs

The three-position switch picks the role of the knobs.

Switch Middle: Global mode

• Main knob: active-track select. The knob travels through tracks 1–6 left to right. Selecting a different active track is a mix action only; it does not reset any track's playhead.
• X knob: playback-layer gain. Centered = unity, fully left = silent, fully right = roughly +6 dB. This is a master-style gain that sits on top of every track's own volume slot.
• Y knob: radiate. Fully left, only the active track is heard. As you turn right, neighboring tracks fade in around the active one until, fully right, all six tracks are heard at the same level. Combined with Main sweeping the active track, this gives a soft cross-fade between tracks and a kind of swept ensemble.

Switch Up: Track mode

Flipping the switch up locks the active track (it will no longer follow Main), and re-tasks every knob to operate on that track:

• Main knob: bipolar speed and direction with a center deadzone. Center = muted hold; turning left plays reverse and turning right plays forward. The further from center, the faster, up to roughly ±2 octaves (¼× ↔ 4×) at the extremes. A small region near center mutes the track to give you a clean "stop".
• X knob: per-track volume
• Y knob: reset start position for this track. It picks the position the playhead will jump to when you trigger a reset (see Switch Down below). Setting Y while the track is playing doesn't move the playhead by itself; it stores the start position for the next reset.

Switch Down

• Tap: reset the active track to its stored start position.
• Hold and move Y: when not armed or recording, moving Y after hard takeover sets the CV2 envelope attack time (instant to ~1 s). The attack setting is latched for future gates. The release time is read from Y when the gate releases.
• Hold for two seconds: arm record mode. While you hold the switch down, the LEDs fill from one to all six as a progress bar; at six LEDs you are armed and the active track's LED begins a slow flash. See Recording below.

CV, Audio In, and Pulse modulation

The CV and pulse jacks add modulation on top of whatever the knobs and switch are doing. CV ranges are the standard Workshop Computer ±6 V.

Outputs

• Audio Out 1 / Audio Out 2 carry the stereo mix. Gridless mode has no pan or filter controls, but each track plays at the pan and low-pass filter last set for it in grid mode or in the sample manager. A track you never panned sits hard on its recorded input's side, with the filter open, as in earlier versions.
• CV Out 1 is a clocked Turing-style pitch output. Pulse In 1 or Pulse In 2 rising edges clock it. Main sets the probability/variation amount, X sets the range (one note up to three octaves) and Y sets the sequence length (3 to 8 steps). These Turing settings follow the knobs in either switch position, and CV In 1/2 don't affect them.
• CV Out 2 is an ASR envelope. Pulse In 1 or Pulse In 2 rising edges clock the CV/Turing output and start the envelope attack; the envelope sustains while either pulse input remains high, then releases when both are low. Switch Down + Y sets attack time (instant to about 1 second); Y at release time sets release time (about 10 ms to 3 seconds).
• Pulse Out 1 emits a short trigger when any playing track wraps back to the start of its loop/playback span.
• Pulse Out 2 emits a short trigger when the CV2 envelope reaches the end of its release cycle.

Inputs

• CV In 1 adds to the X knob (after the panel value, before the X-knob role kicks in). So in global mode it modulates playback-layer gain; in track mode it modulates the active track's volume slot. While a CV is patched, hard-takeover is bypassed on that knob so the CV can take over smoothly.
• CV In 2 adds to the Y knob the same way: radiate in global mode, start-column in track mode.
• Audio In 1, when patched, offsets the active-track selection by an audio-driven amount (0..6 tracks, full-scale). This wraps around the six tracks, so loud audio sweeps the active track through the rotation. Useful for envelopes, LFOs, or rhythmic triggers feeding the track select.
• Audio In 2, when patched, modulates the active track's playback speed, always forward: −6 V → 0.25×, 0 V → 1×, +6 V → 4×. This overrides the speed set by Main (track mode) for as long as it is patched.
• Pulse In 1 rising edge: reset the active track to its stored start column (same as a switch-down tap).
• Pulse In 2 rising edge: advance the active track to the next one (wraps 6→1) without resetting any track's playhead.

A note about audio-driven modulation after recording: once you finish a recording pass, Audio In modulation is held off on each input independently until you unplug and re-plug that input. This stops a still-patched recording source from immediately modulating playback the instant recording stops.

Recording in gridless mode

There is no per-track arm in gridless mode; recording always targets the currently active track. Recording is fixed at 1× speed.

The input jack is picked from whatever is plugged in at the moment recording starts:

• Audio In 1 plugged, Audio In 2 unplugged → captures from Audio In 1 and the track is stored as channel 1 (plays back on Audio Out 1).
• Audio In 1 unplugged, Audio In 2 plugged → captures from Audio In 2 and the track is stored as channel 2 (plays back on Audio Out 2).
• Both plugged or neither plugged → captures from Audio In 1 / channel 1.

The source is locked at the moment recording starts; plugging or unplugging mid-recording does not switch inputs.

1. Hold the switch Down for two seconds. The card LEDs fill from one to six as you hold. At six LEDs you are armed: the active track's LED flashes slowly.
2. While armed, flip the switch Up to cancel and you return to normal playback with no recording made.
3. While armed, push the switch Down again to start recording into the active track. The active track's LED flashes fast.
4. Knob X during recording is the input gain (and monitor level), exactly like the grid-mode armed-record flow. The monitor is routed to the same output (Audio Out 1 or Audio Out 2) the track will play back on, so what you hear while recording matches the post-recording mix.
5. Release the switch from Down to stop the recording, or let the track fill to its maximum length, at which point it auto-stops. After a brief settling delay (~½ second while the new audio is written to flash) the new recording begins looping from the start.

The MLRws sample-manager web app still works in gridless mode: just plug the Computer into a computer running the web app and MLRws will silently switch into sample-manager mode for the duration of the connection, then return to gridless when you disconnect. See SampleMgr.md for details.

LEDs

Brightness shows each track's effective level (volume slot × radiate × playback-layer gain), so you can see at a glance which tracks are loud, which are being radiated into, and where the active track sits. When MLRws is armed for recording or actively recording, only the active track's LED is shown and it flashes (fast = recording, slow = armed/idle).

Tracks are arranged:

1 4
2 5
3 6

Sample manager

The MLRws sample manager is a tiny web app that runs in your browser and talks to the Workshop Computer over USB-serial. You use it to upload audio files from your (non-Workshop) computer onto the card, pull recordings off the card as WAVs, audition or clear individual tracks, and trim/select regions before upload. It is the simplest way to put curated source material on the card without having to play it into the audio input.

• Web app: https://dessertplanet.github.io/MLRws-web/
• Source: dessertplanet/MLRws-web

Getting connected

1. Power-cycle the Workshop Computer into a USB-device mode. The easiest path is to power up with nothing else plugged into the Computer's USB-C port. MLRws comes up in Gridless mode and will transition to sample-manager mode automatically once the web app connects. (If you power up while already plugged into your host computer, MLRws can also boot straight into sample-manager mode.)
2. Plug the Computer into your laptop/desktop with USB-C.
3. Open the web app, click Connect, and pick the Computer's serial port from the browser prompt. The status line will report Connected, and then read each existing track from the card so you can see and audition them.

[!NOTE] This web app requires the Web Serial API to communicate with the WS computer, so a Chromium-based browser is required. Details below

What you see per track

For each of the six tracks the app shows:

• A Speed dropdown. See Record speed and length.
• With firmware 1.2.1 or later, a Pan slider (L6 through C to R6) and a Filter dropdown (250 Hz, 600 Hz, 1.5 kHz, 4 kHz, open). These set the same per-track pan and low-pass filter as the grid's REC page, and Preview plays through them. Older firmware shows a Channel selector instead (see Audio format).
• A CV output toggle for tracks that already contain audio. Empty tracks always send CV1 pitch, gate CV2, and drive pulse outputs from CUT-page grid interactions on their row; populated tracks default to off until enabled here. The toggle is disabled while the web app is disconnected.
• A waveform view with the current crop selection drawn in blue.
• The action buttons described below.
• A small info line showing the current selection length, the maximum length at the chosen speed, and (for tracks that were originally recorded on the Computer panel) the speed they were recorded at (e.g. rec 0.5×).

You can load source audio by clicking Load Audio to pick a file, or by dragging an audio file straight onto the track row. Both work the same way and accept whatever the browser can decode (WAV/AIFF/MP3/FLAC/etc.).

Waveform interaction

The app runs a transient detector on every loaded file and draws each transient as a small tick on the waveform. The transients become sector boundaries for selection:

• Click a sector to select just that sector as the crop region.
• Click-and-drag across the waveform to expand the selection to all sectors between the start and end of the drag.
• Right-click anywhere on the waveform to add a manual sector boundary at that position (useful if the auto-detected transients miss a cut point).

When you change the Speed dropdown while a long file is loaded, the app will snap the end of the crop to the nearest transient before the per-speed length limit (or hard-clamp if no good transient is available).

The action buttons

• Load Audio: open a file picker. (Drag-and-drop onto the row works too.)
• Upload: ADPCM-encode the current selection at the chosen record speed and write it to the card for this track. Replaces any existing audio. Loaded source files are peak-normalized before upload and preview.
• Download: read whatever is currently on the card for this track, decode it, and save it as trackN.wav via your browser's download flow.
• Crop: commit the current crop selection to the audio buffer in the browser (a destructive trim of the working file, not the card). Useful for refining the selection before re-cropping or uploading.
• Clear: erase this track on the card. The browser will ask you to confirm first.
• Preview: play the current track buffer through your laptop's audio output using Web Audio, encoded exactly the way it would be uploaded, with a playhead drawn on the waveform. With firmware 1.2.1 or later it's panned and filtered the way the card will play it (the filter's response matches the card's; only its soft saturation on very loud input is left out). The button becomes Stop while playing; preview loops until you stop it. Changing the speed while playing automatically re-starts the preview at the new setting.

Card settings

With firmware 1.2.1 or later, a settings box above the tracks sets how the card's CV inputs behave in grid mode (see CV inputs):

• CV In 1: pan offset. Tick last touched to follow the last track row you pressed on the grid, or tick any set of tracks 1–6 to offset them all.
• CV In 2: choose Filter cutoff or Rotation, then which tracks it acts on, the same way as CV In 1. In rotation mode, range sets how far +5 V turns the recording (1–100% of the track).

Changes reach the card straight away and are saved to flash when the card leaves sample-manager mode.

Record speed and length

The Speed dropdown controls the record speed the audio is encoded at, in the same sense as recording on the grid mode REC page. Slower record speeds fit more seconds onto the card in exchange for fidelity (ADPCM at a lower sample rate). The options are 0.25×, 0.5×, 0.67× and 1× (default).

Maximum length per track at each speed (firmware 1.2.1 and later):

Record speed	Max per track
1x	26.3 s
0.67x	39.3 s
0.5x	52.6 s
0.25x	105.1 s

When recording on the Computer panel itself (grid mode REC page) you can pick faster-than-1× speeds too. Those tracks will still be displayed and downloadable here, but the dropdown for uploads is capped at 1× because going faster doesn't give you anything useful for a pre-prepared sample.

Audio format

MLRws stores one mono ADPCM stream per track, at 24 kHz for 1× (firmware 1.2.1 and later).

With firmware 1.2.1 or later, stereo source files are mixed down to mono (left + right) before encoding, and each track's Pan places it between Audio Out 1 and Audio Out 2. A track's pan and filter are sent to the card along with each upload, so a fresh upload keeps the pan you set rather than jumping hard left.

With older firmware, each track has a Channel 1/2 selector instead; that selector chooses the stored output routing and, for multi-channel source files, which source channel is encoded. Channel 1 uses source channel 1, Channel 2 uses source channel 2 when present, and single-channel files can be assigned to either output channel.

Each populated track also has a CV output toggle. When it is enabled, touching CUT keys on that track row updates the CV1 pitch sample-and-hold, gates the CV2 ASR envelope, fires Pulse Out 1, and can hold Pulse Out 2 high as a gate. When it is disabled, the track still cuts and can be played normally, but it leaves the CV and pulse outputs unchanged. Empty tracks always update CV1 pitch, gate CV2, fire Pulse Out 1, gate Pulse Out 2 while held, and show the E-major keyboard guide; the pitch map runs left-to-right by semitone with guitar-like row tuning, and repeats on the bottom half of a 16-row grid. Once a track has audio, CV output defaults to off until enabled in the web app.

Uploading always writes only the selected track. With older firmware, use the Channel selector on stereo source files to choose whether source channel 1 or source channel 2 is encoded and which output channel the stored track uses.

Serial transfer notes

The sample-manager protocol is framed so Web Serial packet boundaries do not matter:

• I returns a 32-bit little-endian metadata length followed by that many bytes of text metadata.

• R <track> returns a 32-bit little-endian track length, then streams the track blob in 1024-byte chunks. The browser acknowledges each chunk with A; the firmware sends DONE\n after the final acknowledged chunk.

• P <track> <enabled> updates the populated-track CV output setting.

• Firmware 1.2.1 adds settings commands. Each value byte has its top bit set (0x80 | value) so it can never be mistaken for the X resync, and each replies OK\n or ERR\n:

  • G <0x80|percent>: CV In 2 rotation range, 1–100%.
  • M <0x80|mode>: what CV In 2 drives: 0 = rotation, 1 = filter cutoff.
  • C <0x80|input<<6|mask>: the tracks CV In 1 (input 0) or CV In 2 (input 1) act on; mask bit t = track t+1, 0 = last touched.
  • N <track> <0x80|pan+6>: a track's pan, −6 (hard Out 1) to +6 (hard Out 2).
  • L <track> <0x80|slot>: a track's filter, 0–4 (4 = open).

  The I metadata header reports these as ROT <pct> CV2 LPF|ROT CV1M <mask> CV2M <mask>, and each track line ends with its pan and filter slot.

The web app remembers the selected serial port during the current browser session and attempts to reconnect automatically after a USB disconnect. During reconnect it clears the displayed track buffers first, then repopulates them from the card once sync succeeds.

Browser and Web Serial caveats

The app talks to the Computer via the Web Serial API, which is not as universally supported as the rest of the web. Things to know:

• Use a Chromium-based browser: Chrome, Edge, Brave, Opera, Arc, etc. Firefox and Safari do not support Web Serial as of this writing and the Connect button will do nothing useful there.
• Only one tab can hold the serial port at a time. If a previous tab is still connected (or a different app like the Arduino IDE is), you'll need to close it before connecting.
• On Linux, your user typically needs to be in the dialout (or tty) group to access serial devices. macOS and Windows generally work out of the box.

monome grid API for Workshop System Computer

This document describes the monome API used by the MLRws firmware on the Music Thing Modular Workshop System Computer card.

Compatible with modern mext grids, older series/40h protocol grids, and the FTDI-based monome grids tested with this firmware. DIY grids that speak the same serial protocols over CDC/FTDI should work too.

Files

File	What it does
MonomeGrid.h	Friendly C++ wrapper (the recommended API)
monome_ws.h	Low-level reusable C API (grid/arc types, events, capability queries)
monome_ws.c	Protocol engine for mext, series, and 40h; TinyUSB host/device transport; CDC callbacks
tusb_config.h	TinyUSB configuration (CDC + FTDI host, DTR/RTS, 115200 8N1; also enables CDC device for USB serial)
main.cpp	MLRws card firmware (grid-driven sample looper)
CMakeLists.txt	Build configuration

Test builds

MONOME_WS_FORCE_8X8_MONOBRIGHT=ON forces a modern mext grid to present as an 8x8 binary grid while keeping the mext wire protocol. This is useful for testing monobright UI behavior on modern hardware. In the local MLRws build, use:

make monobright
make flash-monobright

API reference: MonomeGrid.h (C++)

MLRws uses the MonomeGrid wrapper in host mode, but it does not use the grid.begin() convenience path. Instead, the firmware performs explicit monome_ws_init(...) setup and runs the USB loop itself.

Lifecycle

Method	Description
grid.begin()	Convenience helper for standalone use. MLRws does not call this.
grid.ready()	true once grid dimensions are discovered
grid.connected()	true if a device is physically connected
grid.cols()	Grid width (0 before discovery)
grid.rows()	Grid height (0 before discovery)
grid.supportsLevels()	true when the attached grid supports 0-15 LED levels
grid.protocol()	Current backend protocol (MEXT, SERIES, 40H, or UNKNOWN)

Events

MLRws calls grid.poll() during its UI-control pass, not every audio sample. That happens at a reduced rate controlled by MAIN_CTRL_DIV.

Method	Description
grid.poll()	Drain event queue. In MLRws, call during the UI-control tick.
grid.keyDown()	true if a key was pressed this sample
grid.keyUp()	true if a key was released this sample
grid.anyHeld()	true if any key is currently held
grid.held(x, y)	true if key (x, y) is currently held
grid.lastX()	X of the most recent key event
grid.lastY()	Y of the most recent key event

LEDs

LED changes are buffered and flushed by the USB loop on core 1. In MLRws, redraws are built with frame-buffer helpers and submitted with grid.submitFrame().

Method	Description
grid.led(x, y, level)	Set brightness (0–15)
grid.ledOn(x, y)	Set to full brightness
grid.ledOff(x, y)	Turn off
grid.ledToggle(x, y)	Toggle between off and full
grid.ledSet(x, y, on)	Set from a bool
grid.ledGet(x, y)	Read back current level
grid.clear()	All LEDs off
grid.all(level)	Set all LEDs to a level
grid.fill(x0, y0, x1, y1, level)	Fill a rectangle
grid.row(y, level)	Fill a row
grid.col(x, level)	Fill a column
grid.intensity(level)	Set global brightness (0–15)
grid.showHeld(level)	Light all currently held keys
grid.frameClear()	Clear the local frame buffer without submitting
grid.frameLed(x, y, level)	Set a frame-buffer LED with bounds checks
grid.frameLedUnchecked(x, y, level)	Set a known-good frame-buffer LED during redraw
grid.submitFrame()	Submit the accumulated frame when core 1 can accept it

Advanced / direct buffer access

Method	Description
grid.ledBuffer()	Raw uint8_t* to the 16×16 LED buffer
grid.markDirty()	Mark all quadrants for refresh (after writing buffer directly)

Low-level C API: monome_ws.h

For developers who want full control. This is the path MLRws follows in its USB/mode setup:

#include "pico/multicore.h"
#include "bsp/board.h"
#include "tusb.h"

extern "C" {
#include "monome_ws.h"
}

// In your constructor:
monome_ws_init(MONOME_WS_TRANSPORT_HOST, 0);   // host mode, CDC interface 0
multicore_launch_core1(my_core1_func);

// Your core 1 loop:
void my_core1_func() {
    board_init();
    tusb_init();
    while (true) {
      monome_ws_task();     // USB host + monome polling (non-blocking)
        // ... your own core 1 work here ...
    }
}

// In ProcessSample or a lower-rate UI tick on core 0:
  monome_ws_event_t ev;
  while (monome_ws_event_pop(&ev)) {
    if (ev.type == MONOME_WS_EVENT_GRID_KEY) {
        // ev.grid.x, ev.grid.y, ev.grid.z (1=down, 0=up)
    }
}

  monome_ws_grid_led_set(x, y, level);  // buffer an LED change
  // monome_ws_grid_refresh() is called automatically by monome_ws_task()

Key C functions

Function	Description
monome_ws_init(transport, cdc_itf)	Initialise state (MONOME_WS_TRANSPORT_HOST or _DEVICE, CDC interface index)
monome_ws_task()	Poll USB + monome protocols (call from core 1 loop)
monome_ws_connected()	Device physically connected?
monome_ws_protocol()	Current backend protocol
monome_ws_device_kind()	Grid, arc, or unknown
monome_ws_grid_ready()	Grid ready?
monome_ws_grid_supports_levels()	Attached grid supports 0-15 LED levels?
monome_ws_event_pop(&ev)	Pop next event (returns false if empty)
monome_ws_grid_led_set(x, y, level)	Set LED (0–15; older binary grids are thresholded internally)
monome_ws_grid_led_all(level)	Set all LEDs
monome_ws_grid_led_intensity(level)	Global brightness
monome_ws_grid_refresh()	Flush dirty quads (auto-called by monome_ws_task)
monome_ws_grid_frame_submit(levels)	Submit a full 16×16 frame (double-buffered); returns false if busy
monome_ws_grid_all_off()	Send all-off command
monome_ws_send_discovery()	Re-send system queries

Event types

MONOME_WS_EVENT_GRID_KEY   // ev.grid.x, ev.grid.y, ev.grid.z
MONOME_WS_EVENT_ARC_DELTA  // ev.arc.n, ev.arc.delta
MONOME_WS_EVENT_ARC_KEY    // ev.arc_key.n, ev.arc_key.z

Architecture

Core 0                                Core 1
──────                                ──────
ComputerCard::Run()                   board_init() + tusb_init()/tud_init()
  └─ ProcessSample() @ 24kHz         └─ while(true) { monome_ws_task(); ... }
       │                                    │
       ├─ grid.poll() on UI tick            ├─ tuh_task()/tud_task() ← USB stack
       ├─ grid.keyDown() ...                ├─ CDC read/write        ← serial RX/TX
       ├─ frameClear/frameLed/submitFrame   ├─ discovery retry       ← if grid_x == 0
      └─ CVOut / PulseOut                  └─ monome_ws_grid_refresh() ← LED TX @ ~60fps
                    │                                 │
                    └── event queue ──────────────────┘
                        (lock-free SPSC ring)

Hardware compatibility

Grid type	USB chip	TinyUSB driver	Status
Grid (2024+)	RP2040 native	CFG_TUH_CDC	Yes
Grid (2021–2023)	FTDI FT232R	CFG_TUH_CDC_FTDI	Yes
Grid (older)	FTDI FT230X	CFG_TUH_CDC_FTDI	Yes
Series (m64/m128/m256/mk)	FTDI	CFG_TUH_CDC_FTDI	Binary-grid backend
40h / arduinome	FTDI	CFG_TUH_CDC_FTDI	Binary-grid backend
Neotrellis DIY	FTDI	CFG_TUH_CDC_FTDI	Yes
Arc	Same as above	Same as above	Event API reserved; LED-ring output is not used by MLRws

Protocol notes

The driver uses mext when available and can fall back to older series/40h grid protocols behind the same API. Key implementation details (learned from dessertplanet/viii and monome/ansible):

• LED commands are padded to 64 bytes with 0xFF for USB bulk packet alignment. This is essential for reliable operation across all hardware versions.
• Full-frame redraws are copied into a 16×16 frame buffer and flushed as dirty 8×8 quadrants. Modern mext grids receive 0-15 level maps; series/40h grids receive binary maps derived from level > 7.
• The monobright test build also uses the binary level > 7 path, but sends mext binary LED maps so modern grids can be used to validate 8x8 binary UI.
• Discovery queries are sent unpadded: FTDI grid firmware doesn't handle 63 bytes of 0xFF padding after a system query well.
• DTR + RTS must be asserted during USB enumeration. FTDI chips gate serial data through DTR. Without it, the chip enumerates but won't pass bytes.
• Line coding is set to 115200 8N1 automatically via CFG_TUH_CDC_LINE_CODING_ON_ENUM.
• The RX parser skips 0xFF bytes between messages.

Credits

• Protocol implementation modelled on dessertplanet/viii and monome/ansible
• monome for the grid hardware and open mext protocol
• ComputerCard by Tom Whitwell