Neuroscript Guide

Neuroscript is a compact, line-based DSL for quick MIDI transforms. Each line is a step in a linear pipeline. The script is applied top-to-bottom; each step receives the events output by the previous step.

Basics

• One statement per line.
• Lines are evaluated in order.
• pass ends the script with no further changes.
• mute silences all events.

Example:

keep note
transpose +12
vel clamp 10..120
pass

Selectors (Filters)

Selectors describe which events a keep or drop statement targets. You can combine selectors with commas.

keep note, ch 1
drop cc
keep note C2..B3

Supported selectors:

• Event types: note, cc, pc, bend, aftertouch, clock, start, stop, continue, realtime, all
• Channel: ch <n>, ch <a>..<b>, or ch all
• Note range: note C3..G4 or note 60..72
• CC range: cc 1..64

Conditions (where / when)

Use where to add a condition to a keep or drop:

keep note where vel >= 80
drop cc where cc in [1, 7, 10]

Use when to apply an action conditionally:

when note in C3..C4: transpose +12

Operators:

• Comparators: =, !=, <, <=, >, >=
• Boolean: and, or, not
• Lists: in [a, b, c]

Fields:

• type, ch, note, vel, cc, value, prog, bend

Transforms

transpose +7 wrap
octave -1 clamp
vel scale 30..110
vel fixed 80
vel clamp 20..120

Transpose modes:

• wrap keeps notes in range by wrapping
• clamp clamps to 0..127
• drop drops notes that go out of range

Mappings

note C4 -> note D4
note map {
  C4 -> D4
  E4 -> F4
}
cc 1 -> cc 74
ch 2 -> ch 1

Control

pass
mute

Examples

These examples live in scripts/Neuroscript/examples/.

Lo-fi drums

keep note, ch 10
vel clamp 35..95
when vel > 95: vel fixed 85
pass

keep note, ch 10
vel clamp 25..100
note D2 -> note C#2
pass

Ambient pads

keep note, ch 2
octave +1 wrap
vel clamp 40..100
pass

keep note, ch 2
transpose -3 wrap
vel scale 35..110
pass

Utility glue

drop clock, start, stop, continue, realtime
cc 1 -> cc 74
pass

CLI

You can parse scripts via the command line:

swift run neuroscript parse scripts/Neuroscript/examples/09_lofi_drums_soften.ns
swift run neuroscript tokens scripts/Neuroscript/examples/09_lofi_drums_soften.ns

Simulator

A lightweight, static simulator lives at docs/neuroscript-simulator.html. It lets you try single-event scripts in the browser and see the output quickly.