SHOAL

Installing

Shoal uses disting NT plug-in API v13, introduced in firmware 1.15.0. Use firmware 1.15.0 or newer.

The easiest route is the disting NT Plugin Gallery, via the Plugin Manager in nt_helper. To install by hand instead:

1. Download shoal-plugin.zip from the latest release.
2. Unzip it at the root of the disting NT SD card. The archive installs shoal.o at /programs/plug-ins/ormermodular/shoal.o.
3. Restart the module or remount the card so the plug-in folder is scanned.
4. Shoal now appears in the algorithm list (guid Shol).

No compiler or development toolchain is required.

Five minutes to a first melody

1. Add Shoal to an empty preset.
2. It's already ticking. Clock source defaults to Internal at 120 BPM (×1 = one step per beat), so a fresh Shoal runs the moment it lands. To sync it to your rack instead, set Global → Clock source to External and patch a clock (anything above ~1V) into Input 1 - one pulse advances the ×1 tracks one step, so feed it quarter-note pulses.
3. Give Track 1 outputs. All outputs start as None - a track touches nothing until you assign it. On the Routing 1 page set Gate out = Output 2 and Pitch out = Output 1 (gate listed first, matching the other NT sequencers), then patch pitch → oscillator (1V/oct) and gate → envelope (5V). Repeat on Routing 2–8 when you want more tracks - every track starts unrouted.
4. Pick a key. Global → Scale and Root note. Minor pentatonic always sounds good.
5. You should already hear a melody - every seed carries a base line spanning two octaves centred on the root. The bipolar Note and Oct amounts add random variation when you want it wilder; return them to 0 to come home.
6. Reseed until you like it. Tap the right encoder. Each tap rolls a new melody at the top of the next loop.
7. Bring in more fish. Give each further track outputs when you're ready for it. Build the shoal one voice at a time, deliberately.

That's the whole game. Everything else is refinement.

The big ideas

Seeds: randomness that repeats

The seed is the melody. A track's melody is completely determined by its Seed (0–999) - think of it as a recipe number, not a random amount. Same seed = same melody, every loop, every power-up, every preset recall. Reseeding just picks a new number. Because the seed is an ordinary parameter, presets capture your exact patterns - and you can CV-map the seed for pattern-switching madness.

Reseeds land on the grid

A reseed never interrupts mid-loop. It arms (the panel blinks RESEED ARM, the fish swims faster) and takes effect when the track wraps to step 1. New sections start where sections should.

Chance shapes the rhythm

CHANCE - does this step play a note at all? 100% = every step, 50% = half rests. Seeded, so the same steps rest on every loop until you reseed.

The base melody, and non-destructive variation

Every seed produces a base melody: a line spanning two octaves of the scale, centred on the root, so melodies orbit their home note. With Note and Oct at 0 it's exactly what you hear. Two bipolar amounts then add seeded deviation on top:

• NOTE (−100%…+100%) - magnitude sets how often a note is varied and how far it may stray (up to 12 scale steps at full); sign sets the direction.
• OCT (−100%…+100%) - the same idea with whole-octave leaps (up to 5).

Turn them up for wildness, back to 0 for the pure base melody - nothing is ever destroyed. Notes are built from the scale, so nothing is ever out of key.

Tracks can follow each other

Set a track's Sample source to another track and it mirrors that track's material - same musical contour - filtered through its own settings: chance, note/oct amounts, octave, rate, length, gate. Reseed the source and the follower changes with it. Instant related bass lines and counter-melodies, in agreement forever.

Direction: the same melody, walked differently

Direction doesn't change the notes - it changes the walk. Reverse plays your exact melody backwards; Pendulum and Pong fold it into palindromes (ends played twice or once); Drunk staggers (50% on, 25% repeat, 25% back); Random abandons order entirely. Three generative walks go further:

• Tide - the rhythm holds steady while the melody drifts one step through it per pass, realigning after length passes. Deterministic; phases beautifully against a follower playing the unshifted original.
• Shuffle - every step exactly once per pass, freshly dealt each pass. The same notes, their story retold every loop. Even the shuffles are seeded.
• Pools - the playhead circles a pocket of 3–4 steps for a few laps, then hops to another. The closest a sequencer gets to thinking about a phrase.

Six more, from v1.2:

• Stride (Hopscotch) - an overlapping "two ahead, one back" crawl: step 1, step 3, step 2, step 4, step 3, step 5... Each step plays twice across a full cycle, which takes twice the pattern's Length to complete. Fixed and deterministic - every seed hops the same way.
• Gravity - mostly walks forward, but has a seed-derived chance each step of snapping back to step 1 instead - an orbiting, homing pull. The same idea Weight applies to pitch (gravity towards the root), applied here to the walk itself.
• Converge - folds the pattern in on itself: step 1, the last step, step 2, the second-to-last step, and so on, meeting in the middle. Fixed and self-contained - no Sample source needed.
• Diverge - the mirror of Converge: starts near the pattern's middle and alternates outward to both ends, arriving at step 1 and the last step last.
• Skitter - like Random, but never plays the same step twice in a row. Unpredictable without the stutter Random can produce; truly random otherwise (like Random, Drunk and Pools).
• Anchor - alternates step 1 with each other step in turn: step 1, step 2, step 1, step 3, step 1, step 4... A drone note punctuated by melodic excursions, always returning home between them. Fixed and deterministic, unlike Gravity's similar but seed-derived homing pull.

Armed reseeds land at each mode's loop origin (step 1; the last step in Reverse; the pass boundary in Tide/Shuffle; immediately in Random/Drunk/Pools/Skitter). Stride, Gravity, Converge and Anchor land the same way - at step 1. Diverge lands at its own starting point instead - the pattern's middle step, where its cycle actually begins.

Polymetre and rate

Each track has its own Length (1–64) and Rate (/64 … ×64, plus eight non-integer ratios, all in true ascending order). The dial runs /64 /32 /16 /8 /7 /6 /5.3 /5 /4 /3 /2.6 /2 /1.5 ×1 ×1.25 ×1.3 ×1.5 ×2 ×2.6 ×3 ×4 ×5 ×5.3 ×6 ×7 ×8 ×16 ×32 ×64 - the odd ratios (3, 5, 7, plus 6) sit right next to the even ones, so a track at ×3 or /5 pushes against the grid while the rest of the shoal holds it. A 16-step track over a 5-step track at /2 makes phrases that don't repeat for a long time; a 33-step track over anything makes phrases that never seem to. This is where the generative feeling really comes from.

The eight non-integer rates (v1.2) - /5.3, /2.6, /1.5, ×1.25, ×1.3, ×1.5, ×2.6, ×5.3 - slot in at their true position on the dial (e.g. /1.5 sits between /2 and ×1; ×1.5 between ×1 and ×2). /1.5 and ×1.5 are the simplest: where every other rate keeps a fixed number of advances every master tick, these alternate - ×1.5 fires 1, then 2, then 1, then 2 advances per tick (three advances every two ticks, on average - true 3-over-2, no drift); /1.5 fires 0, then 1, then 1 (two advances every three ticks). The other six use exact decimal ratios - not rounded to a "nicer" fraction (×1.3 really is 13/10, not 4/3) - built the same way: each spreads its advances as evenly as possible across a repeating window rather than a fixed count per tick, so the long-run rate is exact with no drift. ×1.25 is the simplest of those six: four ticks, five advances (1, 1, 1, 2 repeating) - the classic 5-against-4 cross-rhythm. ×2.6 repeats every five ticks for thirteen advances. The rest - /5.3, /2.6, ×1.3, ×5.3 - have longer, less obvious repeat windows (10, 13 and 53 ticks), which is rather the point: a lopsided pulse that never quite settles into a short, learnable groove - more texture than tempo.

MIDI (v1.2)

Shoal can send MIDI note out per track, and can be clocked FROM MIDI instead of a CV or internal clock - useful on its own, and it's how Shoal talks to other algorithms on the same disting NT with no cabling at all.

Note out. Each track's Routing page has one MIDI parameter alongside its CV output config: MIDI channel (0 = off - the default, so updating firmware never starts sending MIDI a patch wasn't already asking for). MIDI velocity (1-127) and MIDI dest - a destination bitmask covering Breakout, Select bus, USB and Internal in any combination - are global settings on the Global page, shared by every track that has a channel set, rather than a per-track choice. Internal targets another algorithm on the same NT directly - no patch cable needed. That's a real, tested use case: feeding Shoal into Poly FM (a MIDI/I²C-only algorithm) in one unit. A track is monophonic, so at most one MIDI note sounds per track at a time; a new note always closes the previous one first. Note off fires on the exact same signal that silences the CV gate - natural gate end, mute, or a channel change mid-note - so MIDI timing always tracks the audible gate. Changing the global MIDI dest live closes every track's currently-sounding MIDI note, since one change now affects every track at once rather than just one. One simplification: Tie retriggers over MIDI (fast note-off then note-on) rather than the true legato overlap the CV gate achieves; audibly close on a sound that doesn't retrigger its envelope while gated.

MIDI clock in. Set Clock source to MIDI and Shoal locks to incoming realtime MIDI clock (24 PPQN - Shoal's ×1 is one step per quarter note, so 24 clock messages = one ×1 tick) instead of a CV signal or its own oscillator. MIDI Start resets the pattern to step 1, same as the Reset input; Continue resumes in place; Stop halts it - Run still has to be On as well, exactly as with the other two clock sources, so a DAW's transport and Shoal's own Run switch both have to agree the patch should be playing.

One known limitation: the disting NT gives plug-ins no way to run code when an algorithm is removed from a preset outright (as opposed to muted, frozen, or reseeded, which Shoal does handle). If a track happens to be mid-note at that exact moment, there's no opportunity to send its note-off - the same situation as unplugging a MIDI cable mid-note. Everything else - normal playing, muting, freezing, reseeding, changing a track's MIDI channel or the global destination live - closes notes cleanly.

Currents (v1.2)

Each track can output a Current - a slow, smooth, seeded drift CV, 0-10V, on its own bus (Routing page, Current out). Think of it as "the water the melody swims in": a gentle wandering voltage for filter cutoffs, VCA levels, send amounts, or anything else that wants slow ambient movement alongside the melody, without patching in a separate LFO.

The Shoal twist versus any LFO: a Current is derived from the track's own Seed, so it repeats exactly with every pass, survives power cycles, and is shareable by number - seed 347 always comes with the same current, just like it always comes with the same melody. A fresh target lands every time the track advances a step - whether or not that step actually plays a note, so the Current keeps flowing even on a muted or low-Chance track - and it eases smoothly from wherever it was towards that target over the step, never jumping.

A Current moves at the track's own pace: a fast Rate gives a quicker, more restless drift; a slow one gives a long, gentle swell. A follower's Current is its own - it does not inherit its source track's current, even though it borrows the source's melody, so two followers of the same track get independently-moving water. Currents hold their last value through a Freeze, same as the melody.

Like every output, Current out defaults to None - a track sends nothing until you assign it.

End-of-sequence (v1.2)

Each track can output EOS - a short 5V trigger every time the track completes a full cycle of its Length (Routing page, EOS out). Use it to advance another sequencer, ping an envelope once per phrase, or trigger a reseed on a different track for cascading pattern changes.

EOS counts advances, not loop origin - a deliberate difference from how reseeds/ Evolve/Breathe key off the loop-origin flag elsewhere in Shoal. Random, Drunk, Pools and Skitter have no fixed loop shape, so their loop-origin flag is true on almost every step; wiring EOS to it there would pulse almost continuously rather than marking anything meaningful. Counting Length advances instead gives every one of the 15 Direction modes the same evenly-spaced pulse - Forwards, Reverse, Pendulum and the rest of the ordered modes get it exactly where you'd expect (their own loop origin); the four unordered modes get it at the same steady interval, giving them a sense of "phrase" they don't otherwise have.

EOS isn't gated by Chance or Mute - it marks the sequence's structure, not which steps happen to sound, so it keeps a steady pulse even on a sparse or muted track. It holds silent through a Freeze (nothing advances, so nothing completes a cycle) and, like every output, defaults to None.

The slow arts

Four controls made for long-form and ambient playing.

The performance controls

When Shoal's display is showing, the pots and encoders are live performance controls. Buttons 1–4 keep their normal NT functions.

Push-to-home

Pushing a pot snaps its parameter to the default - the pure seeded melody for NOTE/OCT, full rhythm for CHANCE - and remembers where you were. Push again and your dialled value returns. Punch a track home mid-jam, punch it back: a mute button for chaos. The click itself never edits the value - the pot is ignored for a moment around each push, so a punch-back returns you to exactly the value you left. The pot label on the bottom bar glows while a pot is away from home.

• Soft takeover everywhere: after a home-punch or switching tracks, a knob does nothing until you sweep it through the stored value - no jumps.
• Holds fire after about half a second, while you're still holding. Releasing earlier is a tap.
• Mute keeps the pattern running silently - unmute drops back in on the grid. Mute closes the gates only: pitch CV holds its last note, so a voice that ignores gates (a drone, a self-oscillating filter) sustains rather than going quiet - patch the gate into a VCA or level input if you need true silence. Solo mutes everyone else.

Reading the screen

• 8 rows = 8 tracks: bar height suggests pitch, a flat tick is a rest, lone dots are steps beyond the track's length, the bright column is the play position.
• Longer loops draw denser - up to 16 steps in chunky cells, 17–32 at half width, 33–64 as a fine texture - always fully visible, never scrolled.
• ◄n = following track n. M = muted, S = solo. A dim row without M is breathing.
• Right panel = the selected track's live state: the pot values bright, and beside them DIR (the walk), SD (the current seed - jot down the keepers) and EV (evolve). Below: rate, length, OCT (fixed octave offset) and TR (transpose, in scale degrees). GATE, TIE and SLOP are set-and-forget, so they live on the parameter page only.
• The panel's bottom corner shows the global key (root + scale, e.g. C NMIN), replaced by a blinking RESEED ARM while a reseed waits to land. FRZ appears while frozen.
• The fish is decorative. Mostly. It swims faster when a reseed is armed.

The parameter pages

Exit the custom view and everything lives on 17 standard pages. Every parameter - all 233 of them - is CV/MIDI-mappable and saved in presets. Track parameters are prefixed T1…T8 in mapping menus.

Global

Track 1–8 (each)

Hearing Gate & Tie: these shape gate duration, so they're only audible on voices that follow it - an envelope with sustain (ADSR → VCA) is the classic test rig. Strike-based voices (Rings, plucks, drums, LPG pings) respond to the gate's edge only and will ignore both. For singing ties, add slew on the pitch line: tied notes become slides.

Routing 1–8 (each)

Pitch out / Gate out bus assignments, each with Add/Replace mode (Replace by default - a track owns its busses). Everything defaults to None: a track writes to no bus at all until you assign its outputs. Assign to physical Outputs for your rack, or to aux busses to drive other algorithms inside the preset.

Each routing page also carries the track's output voltages (new in v1.1; the defaults are exactly the old behaviour):

Each routing page also carries the track's MIDI note out (new in v1.2 - see the MIDI section above). Velocity and destination are global settings (Global page, above), shared by every track - only the channel is set per track:

Each routing page also carries the track's Current out (new in v1.2 - see the Currents section above). Like End-of-sequence, it defaults to None and is Replace-only - no Add/Replace mode, a track always owns its Current bus outright:

Each routing page also carries the track's EOS out (new in v1.2 - see the End-of-sequence section above). Unlike the other outputs it has no Add/Replace mode - a trigger bus always owns whatever it's patched to:

Recipes & patching ideas

Every one of Shoal's 233 parameters is mappable - a ramp rising over your set on Evolve, Weight or Chance is form-level automation with no hands. Solo and the pot punch-home gestures are deliberately not parameters: those stay under your fingers. Mute is mappable.

Troubleshooting

My tracks sound like different rates after updating from v1.1.0.

Expected - see the upgrade note in Installing above. v1.2 reordered the Rate dial into true ascending order, which moved almost every rate to a new position, ×1 (the default) included. Old presets load with whatever Rate now sits at the position they saved - go through each track and reset Rate to what you want.

Nothing is moving on screen.

Run is Off, or Clock source is External and no clock is arriving on the input the Clock input parameter points at, or Clock source is MIDI and no realtime MIDI clock (and a Start or Continue) has arrived yet. (A fresh Shoal defaults to Internal and runs on its own.)

No MIDI notes, even with a channel set.

MIDI dest is None, or set to destinations nothing is listening on. Check the track isn't muted or soloed-out either - MIDI note out follows the same mute/solo logic as the CV gate.

A parameter seems dead, or it's stuck at one tempo.

Check the algorithm list for a second Shoal - with two loaded it is easy to edit one while hearing the other.

It's running but silent.

First check the track's Routing page - outputs default to None and a track makes no sound until its Pitch/Gate outs are assigned. Then: Chance at 0? Muted (M)? Another track solo'd (S)? Patched from the output you actually assigned?

Notes seem out of time.

That's probably Slop - set it to 0 for machine timing.

The melody won't get wilder.

Note and Oct are at (or near) 0 - they're bipolar, and the centre of the pot is zero variation. Turn away from centre; positive strays upward, negative downward.

A knob does nothing.

Soft takeover - sweep it through its stored position and it picks up.

The screen turned into fish.

That's the screensaver. Touch anything to come back, or set Global → Screensaver to Off.

The fish screensaver gets replaced by the module's own screensaver.

Expected: the disting NT's firmware screensaver sits above every plug-in, and Shoal's saver can only draw while Shoal's screen is the one showing. To give the shoal the night shift, turn the module's own screensaver off (or lengthen it) in the NT's settings and leave Shoal as the current algorithm.

My preset sounds different after a plug-in update.

If a Shoal update adds parameters, older presets may not line up - re-save them with the new version.

Specifications

• Pitch outputs: 1V/oct, 0V = C3 (MIDI note 48), folded to stay in key at the extremes; per-track scale (5–200%) and offset (±10V)
• Gate outputs: 0V low, high level per track (1–10V, default 5V)
• Clock, reset and reseed input thresholds: rising through ~1V (with hysteresis)
• Clock output: 0/5V pulses at the ×1 step rate, 50% duty; follows Run, and Freeze only if Frozen clock out is set to Stops
• 8 pitch + 8 gate + 8 Current + 8 EOS outputs plus the clock output, freely assignable to any bus (Current and EOS are Replace-only; the rest are Add or Replace)
• Current outputs: 0-10V, seeded per track, independent of Follow (a follower generates its own current from its own seed)
• EOS outputs: 5V trigger, fired from a per-track "every Length advances" counter - independent of Direction mode, not gated by Chance or Mute
• MIDI note out: per track, 1 note at a time, per-track channel; velocity and destination are global (Breakout, Bus, USB, Internal, any combination)
• MIDI clock in: 24 PPQN realtime clock as an alternative to CV or internal clocking, with Start/Continue/Stop transport support
• Memory: under 0.5KB per instance; CPU: light
• Requires disting NT firmware 1.15.0 or later (the release that introduced plug-in API v13) · algorithm guid: Shol