BPscript

Loading WASM module...

Scene

Grammar (BP3)

Output

Messages

Debug

Libraries

Help

(not yet produced)

(no messages)

(no debug info)

Loading reference...

BPscript is a meta-sequencer language. You write rules that describe how musical structures are rewritten, and the engine produces sequences from them.

Directives (@)

Directives configure the compilation environment.

@core                      // load core library
@controls                  // load control definitions
@alphabet.western:browser  // load western note alphabet
@alphabet.raga:browser     // load Indian sargam alphabet
@mm:120                    // metronome: 120 BPM (default: 60)
@mode:random               // derivation type for sub-grammar block

Rules

A rule rewrites a symbol into a sequence.

S -> C4 D4 E4              // S becomes C4 D4 E4
S -> A B                   // S becomes A B (then A and B get rewritten)

The start symbol is always S.

Derivation type (per sub-grammar)

Applied to the entire sub-grammar block. Set with @mode:X before the rules. Persists to following blocks until overridden.

Syntax	BP3	Meaning
`[mode:ord]`	ORD	Rules applied in order (default)
`[mode:random]`	RND	Random rule selection
`[mode:sub1]`	SUB1	Single substitution pass
`[mode:lin]`	LIN	Leftmost derivation
`[mode:tem]`	TEM	Template matching
`[mode:poslong]`	POSLONG	Longest match first
`[mode:sub]`	SUB	Substitution

Scan direction (per rule)

Controls which direction BP3 scans for rule matches. Can differ per rule within a block.

Syntax	BP3	Meaning
`[scan:left]`	LEFT	Scan left to right (default)
`[scan:right]`	RIGHT	Scan right to left
`[scan:rnd]`	RND	Random scan position

Notes & Symbols

Symbol	Meaning
`C4 D#5 Eb3`	Western notes (with @alphabet.western)
`sa6 re6 ga6`	Indian sargam (with @alphabet.raga)
`-`	Silence (same duration as a note)
`_`	Prolongation (extends previous note)
`~`	Tie (legato between two notes): `C4~C4`
`!`	Simultaneous: `C4!E4!G4` = chord

Engine [ ] vs Runtime ( )

[] = BP3 engine instructions. () = runtime/dispatcher controls.

(vel:80) C4 D4         // velocity 80 (runtime)
C4(vel:80)             // velocity 80 after C4
{A B}(vel:100) C D     // vel:100 scoped to group, restored after
[mode:random]          // engine: random rule selection
[weight:50]            // engine: rule weight

Engine [] — BP3 instructions
`[speed:N]`	Tempo ratio for a group
`[weight:N]`	Rule weight for random selection
`[mode:X]`	Derivation mode (random, ord, lin...)
Runtime () — dispatcher controls
`(vel:N)`	Velocity (0-127)
`(chan:N)`	MIDI channel (1-16)
`(ins:N)`	Instrument/program
`(transpose:N)`	Transposition in semitones
`(wave:X)`	Oscillator: sine, triangle, square, sawtooth
`(pan:N)`	Stereo panning (0=left, 64=center, 127=right)
`(attack:N)`	Attack time in ms (default: 20)
`(release:N)`	Release time in ms (default: 100)
`(detune:N)`	Pitch detune in cents (100 = 1 semitone)
`(filter:N)`	Lowpass filter cutoff Hz (0 = off)
`(filterQ:N)`	Filter resonance (default: 1)

Polymetry { }

Curly braces create polymetric groups. Voices are separated by commas and stretched to fit the same total duration.

S -> {C4 D4 E4, F4 G4}        // 3 notes vs 2 notes
S -> {A B, C D E, F G H I}    // 3 voices: 2, 3, 4 notes

Sub-grammars

Use ----- to separate sub-grammars. Each block is applied sequentially until exhausted, then the next block takes over.

S -> A B
-----
A -> C4 D4 [mode:random]
A -> E4 F4

Flags & Guards

Flags are integer variables that control which rules can fire.

Set a flag (in RHS, after ->):

S -> Loop [count=4]           // set count to 4

Guard a rule (before LHS, in []):

[count-1] Loop -> C4 D4 Loop  // decrement count, fire only if count > 0
[count==0] Loop -> C5 _ _     // fire only if count equals 0

Guard syntax	Meaning
`[X-1]`	Decrement X by 1, fire only if X > 0
`[X+1]`	Increment X by 1, fire only if X > 0
`[X==N]`	Fire only if X equals N
`[X!=N]`	Fire only if X not equals N
`[X>N]`	Fire only if X greater than N
`[X]`	Fire only if X is non-zero

RHS syntax	Meaning
`[X=N]`	Set flag X to N
`[X+1]`	Increment flag X

Backticks

Embed code for external runtimes. The dispatcher routes backtick tokens to the corresponding eval transport (requires bridge).

SC_Part -> `sc: Synth(\default, [\freq, 440])`
PY_Part -> `py: print("hello from python")`

Playback

Produce — compile BPscript and run through BP3 engine
Play — play the produced sequence once
Loop — play in a loop; with re-derive checked, each cycle is a new derivation
Stop — stop playback
Live — auto-compile on edit; in loop mode, changes apply at the next cycle