devices/monome/norns.vendor.fw-koiboi2-febc014.jsonEdit on GitHubJSONMonome norns (script KoiBoi2): OSC control from Claude, scripts and controllers
35 named commands to drive Monome norns over OSC — from Claude (MCP), live-coding environments or a MIDI controller.
- sourcemaker's documentation
- firmwarekoiboi2-febc014
- real unitnot yet checked
Not checked on a real Monome norns yet. Own one? Load a sound or send a control, and tell us whether it worked.
- Maker
- Monome
- Version
- script KoiBoi2 (Dillbo/KoiBoi2 @ febc014)
- Source
- maker's documentation
- OSC prefix
/norns_koiboi2
From the README of Dillbo/KoiBoi2 at febc014.
KoiBoi2 Concept
KoiBoi transforms a simple visual metaphor into a rich musical experience:
Koi swim in circular orbits around a pond, each at its own radius and speed
Koi eat the food to trigger notes using the PolyPerc engine
Uneaten food ages and fades into a drone layer over time
MIDI input allows you to place food at specific pitches
Softcut delay adds rhythmic and textural depth
The result is an ever-changing, meditative composition that balances predictability (orbital motion) with randomness (food placement and koi behaviour).
Features
Core Gameplay
Up to 8 koi fish are swimming in circular orbits
Radial pitch mapping: distance from center = pitch (2 octaves)
Dual pitch modes: Linear chromatic or quantised to musical scales
32 food items maximum with brightness-based aging visualisation
MIDI food input: play notes to spawn food at corresponding radii
Sound Engine
PolyPerc synthesis for food notes with adjustable filter, release, and amplitude
Drone layer with a note buffer that loops aged food at adjustable intervals
Tempo-synced delay via Softcut with note division control (1/32 to 4/1)
LFO modulation of delay feedback for evolving textures
Delay filter with adjustable cutoff and resonance
Reverse and overdub modes for creative delay effects
Control & Customization
8-page menu system for deep parameter control
11 musical scales, including major, minor, pentatonic, blues, and modes
Adjustable root note and octave (2-6)
Tempo control (60-200 BPM) with synchronised delay divisions
Per-koi speed and radius control for fine-tuning movement
MIDI input and output on separate channels for food and drone layers
Controls
Main Screen (Page 0)
Control
Function
K1
Enter/exit menu system
K2
Play/Pause
K3
Scatter food into the pond
E1
Select koi (1-8)
E2
Change the selected koi's orbit radius
E3
Change selected koi's speed (positive = clockwise, negative = counter-clockwise)
Menu Navigation
Control
Function
K1
Return to main screen
K2
Test note mapping (prints debug info)
E1
Change menu page (1-8)
E2
Select parameter on the current page
E3
Adjust selected parameter
Instructions Screen
Any encoder scrolls up/down. Press K1 or K2 to exit and start playing.
Menu System
Page 1: Scale & Tempo
Scale: Choose from 11 scales (major, minor, dorian, etc.)
Root Note: Set the root note (C-B)
Octave: Set the base octave (2-6) • Default: 5
Tempo: Set BPM for delay sync (60-200) • Default: 120
Pitch Mode: Linear (chromatic) or Scale (quantised)
Page 2: Koi Behaviour
Number of Koi: 1-8 koi in the pond • Default: 4
Global Speed: Speed multiplier for all koi (0.1-4.0)
Displays selected koi's individual speed and direction
Page 3: PolyPerc Synth
Cutoff: Filter cutoff frequency (50-5000 Hz) • Default: 800 Hz
Release: Note release time (0.1-5.0s) • Default: 0.3s
Amplitude: Note volume (0.0-1.0) • Default: 0.5
Page 4: Softcut Delay
Division: Note value for delay time • Default: 1/4. (dotted quarter)
Use it
Start the bridge with this driver; it forwards named OSC commands to the software:
Then send OSC to 127.0.0.1:7777, for example:
From Claude or any MCP client, the osc-bridge mcp server exposes this driver as norns_koiboi2: ask “what can the Monome norns do?” and it reads this map with list_routes. See the MCP guide.
MIDI controls
35 controls, each with its number, its range and the name to send
OSC commands
| Command | Arguments | Name to send |
|---|---|---|
| Param | id: string, value: float | /norns_koiboi2/param/{id} |
| Param {set} {id} | set: string, id: string, value: float | /norns_koiboi2/param/{set}/{id} |
| Remote key | n: int, z: int | /norns_koiboi2/remote/key |
| Remote enc | n: int, delta: int | /norns_koiboi2/remote/enc |
| Remote brd | code: int, z: int | /norns_koiboi2/remote/brd |
| Param scale | value: int | /norns_koiboi2/param/scale |
| Param root note | value: int | /norns_koiboi2/param/root_note |
| Param octave | value: int | /norns_koiboi2/param/octave |
| Param tempo | value: float | /norns_koiboi2/param/tempo |
| Param pitch mode | value: int | /norns_koiboi2/param/pitch_mode |
| Param num koi | value: int | /norns_koiboi2/param/num_koi |
| Param global speed | value: float | /norns_koiboi2/param/global_speed |
| Param cutoff | value: float | /norns_koiboi2/param/cutoff |
| Param release | value: float | /norns_koiboi2/param/release |
| Param amp | value: float | /norns_koiboi2/param/amp |
| Param delay division | value: int | /norns_koiboi2/param/delay_division |
| Param delay feedback | value: float | /norns_koiboi2/param/delay_feedback |
| Param delay mix | value: float | /norns_koiboi2/param/delay_mix |
| Param feedback lfo rate | value: float | /norns_koiboi2/param/feedback_lfo_rate |
| Param feedback lfo depth | value: float | /norns_koiboi2/param/feedback_lfo_depth |
| Param delay filter cutoff | value: float | /norns_koiboi2/param/delay_filter_cutoff |
| Param delay filter q | value: float | /norns_koiboi2/param/delay_filter_q |
| Param delay reverse | value: int | /norns_koiboi2/param/delay_reverse |
| Param delay overdub | value: int | /norns_koiboi2/param/delay_overdub |
| Param drone amp | value: float | /norns_koiboi2/param/drone_amp |
| Param drone fade chance | value: float | /norns_koiboi2/param/drone_fade_chance |
| Param drone buffer bars | value: int | /norns_koiboi2/param/drone_buffer_bars |
| Param drone buffer notes | value: int | /norns_koiboi2/param/drone_buffer_notes |
| Param drone cutoff | value: float | /norns_koiboi2/param/drone_cutoff |
| Param midi in device | value: int | /norns_koiboi2/param/midi_in_device |
| Param midi out device | value: int | /norns_koiboi2/param/midi_out_device |
| Param midi food channel | value: int | /norns_koiboi2/param/midi_food_channel |
| Param midi drone channel | value: int | /norns_koiboi2/param/midi_drone_channel |
| Param midi input enable | value: int | /norns_koiboi2/param/midi_input_enable |
| Param midi output enable | value: int | /norns_koiboi2/param/midi_output_enable |
The same MIDI as norns.vendor.fw-2.9.4, which this firmware shares.
Limitations
Source: the Lua source of the norns script KoiBoi2 by dillbo (Dillbo/KoiBoi2 at febc014), listed in norns.community. Shares the norns system OSC of monome/norns.vendor.fw-2.9.4 (port 10111, /param, /remote): give the norns' IP address as host override. Its own routes are the 30 parameter(s) whose id is written out in its source, read without running it, with range, options and default when written out too; set them while the script runs on the norns. Parameters added by libraries or engines outside the repository are not mapped either. A value goes in the parameter's units (an option's index from 1). MIDI is not mapped: the script's MIDI handling is its own and parameter MIDI mappings are learned by each user (PMAP). Untested on hardware.
Other versions
The Monome norns is mapped in 356 versions. per Electra preset, per Electra preset, per Electra preset, norns system OSC, v2.9.4, script 32-harmony, script 3d, script 4-big-knobs, script 4CCFader, script abacus, script acid-test, script ack, script acrostic, script amen, script amenbreak, script animator, script arcify, script arcologies, script arp_index, script ash, script ashsynth, script asterion, script automs70, script avonlea, script awake, script awake-ashsynth, script awake-passersby, script awake-rings, script _awed, script b-b-b-b-beat, script bakeneko, script barcode, script barycenter, script beacon, script beets, script benjolis, script bistro, script bitebeet, script bitters, script bline, script blippoo, script blndr, script bloom, script blue, script boingg, script bounds, script bowering, script breakthrough, script buoys, script caliper, script carter's delay, script cc-canvas, script cccccccc, script changes, script cheat_codes_2, script choukanzu, script circles, script clarck, script clcks, script clipper, script clockabout, script colorwheel, script combiner, script combos, script compass, script concrete, script constellations, script corners, script cranes, script crow_talk, script cryptkeeper, script cybermidi, script cyrene, script d, script delar, script delayyyyyyyy, script delinquencer, script demoncore, script descartes, script dimension-expander, script downtown, script dreamsequence, script drift, script dronecaster, script drum_room, script duatone, script dunes, script Eastwind, script easygrain, script eels, script ekombi, script endless-stairs, script esper, script eterna, script euclidigons, script faeng, script fall, fates 2.9.3, script fiahod, script fibonacci, script fixed-filter-banking-crisis, script flora, script fm7, script folio, script footfoot, script forge, script foulplay, script foundry, script fugarc, script fugu, script gematria, script gemini, script get in the sea!, script giro, script glaciers, script glitchlets, script glitchlooper, script glut, script goldeneye, script grains, script graintopia, script granchild, script grd, script grendy, script greyhole, script grid-test, script gridofpoints, script gridofrings, script gridstep, script groovecats, script grurder, script hachi, script hands, script haven, script haze, script here-there, script hid_demo, script Hiswing, script hpns, script hs010, script icarus, script iiitoii, script impact, script ingenue, script initenere, script internorns, script interpret, script intervaltrainer, script islands, script isoseq, script jala, script jiffy, script just-play, script justharmonicon, script kolor, script kreislauf, script kria_midi, script krill, script l_ll__l_, script lamellae, script lamination, script larc, script lemniscate, script leslie, script less-concepts, script lissadron, script loom, script lorenz, script lorenzos-drums, script loudnumbers_norns, script luck, script m18s, script magnetar, script magpie, script makebreakbeat, script mangl, script manifold, script marcovaldo, script massif, script MDPatch, script MDScaler, script meadowphysics, script metrix, script metronome, script midarto, script midi-monitor, script midi-review, script midididi, script midigrid, script midiplayer, script mlr, script mlre, script Mnmpatch, script molly_the_poly, script moln, script monitor, script monomaniac, script moonraker, script mosaic, script mouse, script mx.samples, script mx.synths, script n.kria, script nørgård, script n16o, script nameless-nightmare, script narf, script nb_drumcrow, script nb_mxsynths, script nb_plyprc, script nb_smpKit, script nc01-drone, script nc02-rs, script nc03-ds, script ndls, script nice-tapes, script nisp, script nmMelodyMagic, script nmQuadroDubber, script nmRain, script nmSmartyPants, script noize, script noizeop, script norman, script norns.online, script nornsfetch, script nydl, script o-o-o, script oblique, script oilcan, script onehanded, script ong, script oooooo, script orbital, script orca, script orgn, script orgnwrms, script ortf, script otis, script overtones, script overwintering, script p8, script paracosms, script paranibbles, script parrot, script passersby, script passthrough, script patchwork, script path-trace, script pedalboard, script phonotype, script phyllis, script pirate-radio, script pit-orchisstra, script pitfalls, script pitter-patter, script piwip, script pixels, script plasma, script plonky, script pools, script ppm_norns, script punchcard, script qfwfq, script quence, script r, script rachim, script raft, script raindrops, script randomizer_typhon, script rangl, script rebound, script reels, script repeater, script repl-looper, script ribbons, script rpls, script rpmate, script rudiments, script sam, script sampswap, script samsara, script samthree, script sath-lemon, script schicksalslied, script scholastic, script scryingstone, script seaflex, script seeker_ii, script sempra, script serialism, script shapes, script shfts, script shnthsalslied, script showers, script sidvagn, script silos, script sines, script skylines, script smash, script sonde, script spirals, script splicer, script splnkr, script stack, script step, script stjörnuíþrótt, script streams, script strides, script strum, script stwnsh, script SuperBrain, script supertonic, script sway, script sweet bees, script synthy, script takt, script tambla, script tapedeck, script taweeet, script tetra, script tetrabobo, script tetrabotis, script thebangs, script thirtythree, script thorns, script Tidbit, script timber, script time-rhythm, script timeparty, script tmi, script torii, script traffic, script triangles, script tulpamancer, script tuner, script tunnels, script turntable, script tviburar, script twine, script twins, script u, script ufo, script uhf, script vcr, script vinker, script warmreload, script waver, script window-crowparator, script wobblewobble, script wrms, script xD1, script Ygg, script yggdrasil, script zellen, script zxcvbn.
Frequently asked questions
Can an AI agent like Claude control the Monome norns?
Yes: SynthHub's hosted MCP server knows the Monome norns's MIDI map, and its browser relay lets the agent send it parameter changes or load a sound, each sound change confirmed by you.