Interactions in MIDI and Csound

    

To understand this part in the MIDI environment, you need to read Real-time MIDI.

Several BP3s performing and communicating

From the previous description of interactions via MIDI events — limited for the time being to waiting for a particular note — you may have guessed that a great feature of the Bol Processor BP3 environment is the possibility of running several BP3s, on different machines, or even on a single machine and the same browser… in cooperation with real humans playing MIDI instruments!

Each instance of BP3 can be thought of as a 'musician' with their own compositional skills embedded in a grammar or data (a set of pre-composed musical fragments). We are working on interactions that will allow each musician to modify the behaviour of another musician's grammar, for example by changing rule weights — which may result in some rules being suppressed while others are activated — or changing metronome settings if they need to perform faster/slower, etc. All these features were part of earlier versions (BP2) several decades ago!

Let us start with an extremely simple example using the "wait for note…" script.

Create two projects that contain only data, for example "-da.Beatrix" and "-da.Alan":

-se.Beatrix
{2, C#4 Eb4 A4 G#4 C4 Bb4 F#4 G4 B4 D4 E4}

-se.Alan
_script(wait for E4 channel 1) {2, - F3 C#3 Eb3 A3 G#3 C3 Bb3 F#3 G3 B3 D3 E3}

Note that these melodies do not contain the same number of notes, but they will have the same duration (2 beats) because of their polymetric structures.

We want Alan's performance to start precisely after the last note of Beatrix's performance. As we don't want E4 to overlap with F3, we have put a silence '-' before F3. In the following, we'll have a solution to overcome this limitation.

To manage the interaction in MacOS, we need an additional IAC port which is (automatically) named "Bus2". To do this, open Audi MIDI Setup and click on the IAC driver. Then add a port (see picture). You can create as many ports as you wish.

Set both Beatrix's MIDI output and Alan's MIDI input to "Bus2".

Now we want to hear both performances. Alan's MIDI output is sent to "Bus1" and will therefore be audible on the Pianoteq synthesiser.

Windows and Linux users can connect the two performers more easily: send both Beatrix's and Alan's messages to the external MIDI device, and connect Alan's input to the same MIDI device. But… the input filter should receive events and not forward them to the output, which is the same device, otherwise the loop will produce a disastrous bouncing effect!

Back to MacOS, there are two ways to send Beatrix's performance to the Pianoteq synthesiser:

  • Pianoteq settings make it possible to listen to both "Bus1" and "Bus2" virtual ports.
  • You can set up the MIDI event filter on Alan's project to route input NoteOn/NoteOff events to the current MIDI output. See above for filters.

To play the performance, click PLAY on Alan's project so that it is ready to perform. Then click PLAY on Beatrix's project. This is the result:

Two phrases played in sequence by two instances of the BP3 (Beatrix & Alan).

No doubt this sounds rather unmusical! In fact, we publish tasteless technical examples to encourage musicians to compose interesting pieces! 😀

Using out-time inaudible notes as signals

The idea of beginning Alan's performance with a silence that is filled by Beatrix's final note E4 is unelegant. Below is a better solution:

-se.Beatrix
{2, C#4 Eb4 A4 G#4 C4 Bb4 F#4 G4 B4 D4 E4} _vel(0) <<C0>>

-se.Alan
_script(wait for C0 channel 1) {2, - F3 C#3 Eb3 A3 G#3 C3 Bb3 F#3 G3 B3 D3 E3}

The secret is the expression "_vel(0) <<C0>>" which is an out-time expression of note C0 with velocity zero. The velocity ensures that the note won't be heard, and the out-time property gives it a null duration. Any note can be used here provided that it is mentionend in the "_script(wait…)" instruction.

If "_vel(0) <<C0>>" is followed by more notes, it is necessary to reset the velocity to its default value. The solution is to write it between curly brackets, so that _vel(0) only applies to the content of the expression: "{_vel(0) <<C0>>}"

Checking the time accuracy

Let us check that the real-time synchronisation is not affected by delays. We'll now ask Alan and Beatrix to play the same piece of music (one octave apart) in the same time.

This time, Alan will start:

_transpose(12) _vel(60) E2 • D2 E2 • _vel(65) B2 D2 E2 • G2 B2 D2 E2 • _vel(70) F#2 G2 B2 D2 E2 • Bb2 F#2 G2 B2 D2 E2 • _vel(75) C2 Bb2 F#2 G2 B2 D2 E2 • _vel(77) G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(80) A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(85) Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(87) C#2 Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(90) F2 C#2 Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 _vel(0) <<C0>>

In MacOS, Alan will send MIDI events to "Bus2". Beatrix will listen to "Bus2" and send MIDI events to "Bus1" (Pianoteq). Beatrix will set her input filter to the pass option, routing the incoming events to the output. The Pianoteq synthesiser will be set to listen to "Bus1" only.

This is the score of Beatrix:

_script(wait for C1 channel 1) _transpose(24) _vel(60) E2 • D2 E2 • _vel(65) B2 D2 E2 • G2 B2 D2 E2 • _vel(70) F#2 G2 B2 D2 E2 • Bb2 F#2 G2 B2 D2 E2 • _vel(75) C2 Bb2 F#2 G2 B2 D2 E2 • _vel(77) G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(80) A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(85) Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(87) C#2 Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2 • _vel(90) F2 C#2 Eb2 A2 G#2 C2 Bb2 F#2 G2 B2 D2 E2

To start the performance, first click on the PLAY button of Beatrix's project, then on the PLAY button of Alan's project.

Have you noticed that Beatrix is waiting for C1, which does not appear in Alan's score? Oh yes, it does! There is a _transpose(12) command that changes C0 (the first note) to C1. So, it works. This is the performance:

Two superimposed performances (one octave apart), played by two instances of the BP3 (Beatrix & Alan).

Not too bad? Despite the lack of musical interest, we must admit that the superimposition is technically acceptable, even if it is not perfect: there is a delay of about 60 milliseconds on the first note, the time it takes Beatrix's machine to detect that it has received a NoteOn for C1. The subsequent notes are programmed to compensate for this delay, but there are still discrepancies (which can be quantified on the Pianoteq MIDI input). They seem to be caused by delays outside BP3.

You can adjust the delay in Beatrix's project settings "-se.Beatrix". There is a parameter called "Sync delay", which is the number of milliseconds Beatrix's output events should be postponed after the synchronisation. We currently find that 380 ms is a good value.

In fact, the superimposition would sound even better if both performances were triggered by the same event, such as the conductor pressing a key on the external keyboard. This exercise was only intended to show that synchronisation between "virtual musicians" works well.

This example does not work with real-time Csound. We will show solutions later.

Working with multiple MIDI inputs

In the previous example, we could decide that Alan's performance will start when he receives a particular note from the Pocket Key 25 keyboard. In this case, we need to click on both START buttons, putting both 'musicians' in wait mode, and the performance will not start until the correct key is pressed on the keyboard.

This case is manageable with single inputs on each instance of BP3. More complicated cases, however, require external 'actors', such as a Pocket Key 25 keyboard sending to all the 'musicians' synchronisation messages, or messages modifying parameters in grammars, changing the metronome value, etc.

To achieve this, the Bol Processor is a able to manage multiple MIDI inputs.

The new game is as follows: both Beatrix and Alan will take turns playing variations of Mozart's musical dice game (see '-gr.Mozart'), one octave apart. They will use the Improvise mode to continue throwing the dice and creating unheard variations. But they will wait for a signal from the other to start playing a new variation.

In short, both musicians will use the same grammar, with only a small change for mutual synchronisation. Their settings must be carefully adjusted:

  • Select Italian/Spanish/French as a note convention
  • Check Non-stop improvise
  • Adjust Pclock = 3 and Qclock = 11 to get the same metronome speed of 220 bpm
  • Set Sync delay to 380 ms
  • We don't want both musicians to repeat the same variations. So, set the Seed for randomization to different values, for instance '1' and '2'. Or set it to zero to instruct the machine to seed the random sequence with an arbitrary number of its choice.

In the current version of BP3, the easiest way to send a signal is to send a note with a velocity of zero, which will therefore go unheard. So we need to change the grammar to add these particular notes.

In fact, the same notes should never be part of the score, so that the signal is really sent at the end. This is easy with Mozart's game, for example we can use C# (do#) for the synchronisation. Below are the tops of the grammars used by Beatrix and Alan.

Beatrix '-gr.Beatrix':

-se.Beatrix
ORD
gram#1[1] S --> _script(wait for do#3 channel 1) _vel(80) A B _vel(0) <<do#2>>
gram#1[2] A --> A1 A2 A3 A4 A5 A6 A7 A8 A1 A2 A3 A4 A5 A6 A7 A'8
gram#1[3] B --> B1 B2 B3 B4 B5 B6 B7 B8 B1 B2 B3 B4 B5 B6 B7 B8
-------------------
LIN [Select rules randomly and apply from left to right]
etc.

Alan's '-gr.Alan':

-se.Alan
ORD
gram#1[1] S --> _script(wait for do#2 channel 1) _vel(80) _transpose(-12) A B _vel(0) <<do#4>>
gram#1[2] A --> A1 A2 A3 A4 A5 A6 A7 A8 A1 A2 A3 A4 A5 A6 A7 A'8
gram#1[3] B --> B1 B2 B3 B4 B5 B6 B7 B8 B1 B2 B3 B4 B5 B6 B7 B8
-------------------
LIN [Select rules randomly and apply from left to right]
etc.

Again, we put do#4 at the end of Alan's performance because it is played as do#3 (one octave lower) due to the _transpose(-12) instruction.

Notes <<do#3>> and <<do#4>> are out-time, which means that their duration is 0. When this performance is played in real-time Csound, only notes with duration zero are sent to the MIDI environment.

Now we need to set up the MIDI inputs and outputs. Beatrix will send events to "Bus 1" which is the Pianoteq synthesizer. She will receive events from "Bus 2", use them for synchronisation, and forward them to the output.

Alan will send events to "Bus 2" and listen to "Bus 1" for the synchronisation.

This is all perfect on paper, but who is going to start? We have created a chicken and egg situation, so we need a superpower to start the process! Actually, a real human pressing the do#2 key on a Pocket Key 25 keyboard will start Alan's performance.

The interface has a Add an input button. We click it on Alan's project and paste the name Pocket Key 25. We also use the comment fields to remember the use of each port:

MIDI inputs and outputs are identified by their names. The numbers in the leftmost boxes are automatically set by the console during performance.

To start the concert, we'll click START on both projects. The order is irrelevant. Then we'll press a key on the Pocket Key 25. Which key?

If we press the do#2 key, we will certainly trigger Alan's improvisation and the cycle will start. But if we press the do#3 key, nothing will happen because, by default, the filter of the Pocket Key 25's input in "-gr.Alan" does not transmit NoteOns to the output. So Beatrix won't hear it… By setting NoteOn to status '2' (treat and pass) on this filter, it is possible to decide who will start the performance: do#2 for Alan and do#3 for Beatrix.

Here we go (starting with Alan):

Alan and Beatrix (two instances of BP3) playing variations of Mozart's musical dice game

You can interrupt this dual performance at any time by clicking the Pause button (of either project) and resume it by clicking the Continue button. You can also insert musical fragments by running a project such as "-da.tryStopContinue" (see below), if Stop and Continue MIDI events are sent to both "Bus 1" and "Bus 2" ports. In both cases the synchronisation is maintained.

👉  This simple show should convince musicians to create "virtual bands" of BP3s playing different grammars and sending specific synchronisation signals according to which variation has just been produced. Along with human performers who join in the fun!

The "virtual musicians" can be on the same computer or remotely connected via network (BlueTooth) or MIDI cables and USB interfaces. If they are on the same computer, they can be run on different browsers and/or the same browser. In the latter case, BP3 will not allow the same project (grammar or data) to be run in the same session. In general, just like human musicians in an orchestra have individual scores, it makes sense that virtual musicians don't share the same project…

The number of MIDI inputs and outputs in a project is currently limited to 32. It is unlikely that a (human) musician will need more!

Synchronise to a sequence (or list) of notes

The following expression

gram#1[1] S --> _script(wait for C3 channel 1) - _script(wait for E3 channel 1) etc.

synchronises the production to the sequence of notes C3 E3 (whatever the duration and velocity). This creates interesting situations where a "virtual musician" is expected to start playing after receiving a signal (C3) from one partner, then a signal (E3) from another partner.

Note that there is a silence '-' between the two script instructions. If there is no silence, then BP3 will resume playing if either C3 or E3 has been received.

Remember that because of the MIDI channel specification (range 1 to 16), the detection of signals can be selective. They are also inaudible when transmitted by NoteOns with velocity zero.

Crashing the band!

In the example of Alan & Beatrix playing Mozart, the connection seems to create a loop: Beatrix sends events to Pianoteq and Alan ("Bus 1"), who in turn sends events to Beatrix ("Bus 2"). Isn't that dangerous?

The reason it doesn't crash is that Alan's input "fromBeatrix" ("Bus 1") is filtered: NoteOns are received and processed (for synchronisation), but not passed to the output ("Bus 2"), i.e. to Beatrix. You can try to change the filter of input "Bus 1" on Alan's project, setting NoteOns to status '2' (treat + pass): you will get a superb crash after a flood of notes!
➡  This probably will not happen because BP3's MIDI drivers have been equipped with an anti-bouncing mechanism.

Working with multiple MIDI outputs

The Bol Processor currently accepts up to 32 MIDI inputs and outputs.

Example of a project using two inputs and two outputs:

A setup with two MIDI outputs and two MIDI inputs

The procedure for adding outputs is the same as the one for adding inputs: click on the Add an output button, then enter the name of the MIDI device if you know it exactly, otherwise leave it blank and let the machine connect it by default to the next available output, while suggesting other options:

🎹 Your real-time MIDI settings:
MIDI output = 0: “Bus 1” - Pianoteq
MIDI output = 3: “USB MIDI Interface” - Yamaha piano
MIDI input = 1: “Bus 2” - from Alex
MIDI input = 2: “Pocket Key 25” - a small keyboard

🎹 Setting up MacOS MIDI system
MIDI output = 0: “Bus 1” 👉 the name of your choice
MIDI output = 3: “USB MIDI Interface” 👉 the name of your choice
MIDI input = 1: “Bus 2” 👉 the name of your choice
MIDI input 1 makes BP3 interactive
MIDI input = 2: “Pocket Key 25” 👉 the name of your choice
MIDI input 2 makes BP3 interactive

🎶 More MIDI output options were available:
MIDI output = 1: “Bus 2”
MIDI output = 2: “Pocket Key 25”

🎶 More MIDI input options were available:
MIDI input = 0: “Bus 1”
MIDI input = 3: “USB MIDI Interface”

The fact that a MIDI input or output is "available" does not guarantee that it will do what we want it to do. For example, sending MIDI messages to the Pocket Key 25 keyboard will actually do nothing.

Filtering MIDI outputs

In the example above, MIDI output 3 (the Yamaha piano connected to the USB MIDI Interface) has the filter shown on this picture.

The channel filter specifies that the Yamaha piano will get all MIDI channels except those emitted on MIDI channel 2. Filtering MIDI channels makes it possible to send events exclusively to different instruments.

MIDI events can also be filtered by type. The idea is the same as for MIDI input filters, see above.

Filtering on parts has been explained above.

👉  If you do not hear any sound in real-time MIDI, you may consider checking the output MIDI filters before you kick the piano or screw up its cables!  😀

Using standard MIDI control

MIDI has standard control messages, namely Start, Continue and Stop, which can be used to coordinate multiple "virtual musicians" (instances of BP3). The advantage is the clarity of the data and the grammars programmed for interactions. The disadvantage is that these messages are not assigned to specific MIDI channels. This can be a problem with a large number of "virtual musicians". They also introduce a delay of about 250 milliseconds due to the time it takes for the MIDI device to process them.

Control messages can be used in two ways. The first, which we will now examine, is to "listen" to these messages via a script command. The second (see next section) is to respond to them as interruptions in the performance.

These control messages are also sent and received via MIDI channels when the performance is played by real-time Csound.

Let us look at a trivial example (of no musical interest), again with Beatrix and Alan playing together. This time, they take turns playing their items (simple sequences of notes).

Alan will start first. Below is the data:

E3 D3 C3 _script(MIDI send Start) _script(wait for Continue) A2 B2 C3

In short, he will play three notes (E3 D3 C3), then send a START to Beatrix and wait for a CONTINUE from Beatrix, then on receipt play the final three notes A2 B2 C3.

This is Beatrix's data:

_script(wait for Start) E4 D4 C4 _script(MIDI send Continue)

Start and Continue should be "heard" by Beatrix. Automatically, Stop will have the same status.

Beatrix's project sends its output to "Bus 1", the Pianoteq synthesizer. Its input is connected to the virtual port "Bus 2".

Alan's project sends its output to the virtual port "Bus 2", and its input is connected to "Bus 1".

We'll start the performance with Beatrix. Her machine will stay waiting for START. Then we'll start Alan's part, which will play three notes, then send a START message to Beatrix, who will play her part, and return to Alan, via a CONTINUE message, for the final part…

This all sounds logical, but it doesn't work! We do hear Alan's E3 D3 C3, but then nothing… The first reason is that Beatrix should be able to hear Alan's START command, which is no longer a NoteOn as in the previous examples. This means that the filter of her input "Bus 2", from which she receives Alan's MIDI messages, must be set correctly. The Start event should be received, see picture on the side. Also remember that NoteOn and NoteOff should be received and transmitted to the output (the Pianoteq synth).

Well, now we hear Alan's E3 D3 C3 followed with Beatrix's E4 D4 C4, but then… nothing! 😢

Careful analysis is needed to solve the problem. However, this is simple logic. Remember that Alan is playing on "Bus 2", which is not connected to any MIDI device. If we hear Alan's production, it is because it is received by Beatrix on "Bus 2" and then forwarded to "Bus 1" (the Pianoteq synth). The problem is that the final part A2 B2 C3 is sent to Beatrix, but she has already stopped listening because her own data is finished!

You can imagine a band in which one musician plays an improvisation and then gives a signal to another musician to start their own improvisation, but the careless musician has already vacated the place believing that the programme was finished. The solution is to tell the musicians not to go away until they receive a STOP signal. Maybe a signal from a conductor (here using the Pocket Key 25 keyboard), maybe a signal from the musician who is in charge of ending the performance. So we'll tell Alan to send a STOP signal at the end of his performance, and Beatrix to wait for Alan's STOP signal. Below are the revised scores.

// Alan
E3 D3 C3 _script(MIDI send Start) _script(wait for Continue) A2 B2 C3 _script(MIDI send Stop)

// Beatrix
_script(wait for Start) E4 D4 C4 _script(MIDI send Continue) _script(wait for Stop)

The MIDI messages Start, Continue, Stop have been used here to facilitate the reading of scores (or grammars), but these can be replaced by NoteOns with durations and velocities zero on different MIDI channels when working with a larger number of actors.

By the way, using MIDI messages Start, Continue and Stop can be problematic with physical or virtual MIDI devices. My Yamaha piano, for example, does not transmit these messages. So, when connected to an input, it will only send 3-byte messages such as NoteOn/NoteOffs. In the Windows environment, the Microsoft GS Wavetable Synth also does not transmit any message at all. The best way to exchange messages is via virtual MIDI ports created by "loopMIDI" (see below). In Linux, virtual ports such as 'VirMIDI 0-0' (see below) do not seem to transmit these Start, Continue and Stop messages.

For geeks: In the Bol processor, scripts are appended to the next following sound object. For example, _script(wait for Start) is appended to note E4 in Beatrix's score. But what about scripts at the end of a score? The secret is that BP3 creates an invisible MIDI event (ActiveSensing) at the end of each element to which it can append the final scripts.

Using control messages to interrupt a performance

This is the second way of using control messages. Let's try to stop a performance with a standard Stop MIDI message, play a few notes and then continue the performance with a standard Continue MIDI message.

We create a project "-da.tryStopContinue" as follows:

-se.tryStopContinue
_script(MIDI send Stop) _tempo(2) A2 G#2 C2 Bb2 F#2 G2 B2 _script(MIDI send Continue)

Running this project will interrupt a performance, for example "-da.Watch_What_Happens_by_Oscar_Peterson". For this to work, the "Respond to Stop/Continue" option must be checked in the Oscar Peterson data project.

Let us decide that the performance will be played on the Pianoteq synthesiser connected to "Bus 1" on a Mac.

The "-da.tryStopContinue" will send its data to a virtual port, for instance "Bus 2". To this effect, the "-da.Watch_What_Happens_by_Oscar_Peterson" project will have an input port listening to "Bus 2", accepting all messages and transmitting at least NoteOn/Noteoff.

Another solution is to set up another output port on the "-da.tryStopContinue" project, that sends all data to "Bus 1". The output to "Bus 2" will only send the Stop and Continue messages. The input port listening to "Bus 2" on the Oscar Peterson project will only accept Stop and Continue, and not transmit anything.

👉  It is a good practice to use the filters for restriction of message management to the necessary tasks.

Now, play the Oscar Peterson performance, and at any point start "-da.tryStopContinue". The performance will pause and you will hear the external musical phrase. The performance will then resume. You can, of course, do this several times and insert any variety of musical fragments. For example:

Beginning of Oscar Peterson's "Watch What Happens" with two interruptions

List of scripts for dealing with real-time MIDI

The list below will be kept up to date as there are many scripts on the agenda. These instructions are not case-sensitive.

Scripts tagged [Csound] also work in real-time Csound.

Input scripts

When a note is specified, be sure to use the same note convention as in the project, e.g. C3 or do2 or sa3, etc.

Beware that interactions are limited in Csound because MIDI notes are not transmitted. Therefore, the machine will only react to instructions Start, Continue, Stop, Wait forever, Hold for, and Wait for note if the note has been sent by another MIDI device.

Wait for note channel cWait for a NoteOn of the specified note on channel c (1…16) [Csound]
Wait for StartWait for a Start MIDI message (250) [Csound]
Wait for ContinueWait for a Continue MIDI message (251) [Csound]
Wait for StopWait for a Stop MIDI message (252) [Csound]
Wait foreverWait until STOP or PANIC button is clicked [Csound]
Velocity param Kx = note channel cSet parameter Kx (0 < x < 128) to the velocity (range 0…127) of the specific note on channel c (1…16)
Control param Kx = #y channel cSet parameter Kx (0 < x < 128) to the value (range 0…127) of MIDI controller #y (0 < y < 128) on channel c (1…16)

Output scripts

Hold for x millisecondsDelay all subsequent events by the specified duration x (integer). [Csound]
Send StartSend Start MIDI message (250) [Csound]
Send ContinueSend Continue MIDI message (251) [Csound]
Send StopSend Stop MIDI message (252) [Csound]

Scripts on top of a grammar

(To be continued)

Capture incoming events

The _capture() command allows incoming MIDI events to be recorded to a 'capture' text file. See the Capture MIDI input page for explanations.

Alternatives to IAC

Here are the equivalents of Apple's IAC (Inter-Application Communication) for each system:

Windows environment

On Windows, you can use software like loopMIDI or virtualMIDISynth to create virtual MIDI ports. These tools work similarly to the IAC Driver on macOS:

These tools integrate with software applications that support MIDI, providing a seamless way to connect various MIDI applications without needing external MIDI hardware.

Linux environment

On Linux, ALSA (Advanced Linux Sound Architecture) provides capabilities to create virtual MIDI devices through its sequencing API.

  • snd-virmidi: This ALSA MIDI driver provides virtual MIDI ports for sending and receiving MIDI between applications running on the same system. It's part of the standard ALSA module set and can be configured to provide multiple ports.

To set up virtual MIDI ports on Linux using ALSA, you typically need to load the snd-virmidi module. You can do this by running:

sudo modprobe snd-virmidi midi_devs=2

This command loads the snd-virmidi module and sets it up to provide two virtual MIDI devices (you can increase the number of devices by changing the midi_devs parameter). The virtual ports, namely 'VirMIDI 0-0' and 'VirMIDI 0-1' , can then be accessed by MIDI applications on the Linux system. Please note that they do not appear to transmit the Start, Stop and Continue messages.

👉 This is done automatically by the "install_bp3.sh" shell script installing BP3 on Linux/Ubuntu (download here).

Tonality

MIDI microtonality
This page is a demo of the handling of microtonality in the real-time MIDI and MIDI file environments of the Bol Processor BP3 (version 3.0.7 and higher). Install BP3 by …
Tonal analysis of musical works
Musical works using "simple notes" can be analysed in terms of harmonic or melodic intervals, and matched against specific tuning schemes …
Microtonality
On electronic instruments such as the Bol Processor, microtonality is the matter of "microtonal tuning", here meaning the construction of musical scales outside the conventional one(s) …

Live

Interactions in MIDI and Csound
To understand this part in the MIDI environment, you need to read Real-time MIDI. Several BP3s performing and communicating From the previous description of interactions via MIDI events — limited …
Live coding
Live coding is a performing art form centred on writing code and using interactive programming in an improvisational way. From March 2025, this practice is possible on all Bol Processor …
Capture MIDI input
Work in progress Capturing MIDI input opens the way to "learning" from the performance of a musician or another MIDI device. The first step is to use the captured incoming …

Compute

Learning rule weights
The "learning rule weights" feature was implemented in the first version of the Bol Processor (BP1) a long time ago. It was designed in response to a problem that arose …
Parsing music
The Bol Processor can analyse musical variations (strings of terminal symbols) using a grammar. A successful parse (membership test) indicates that the variation was produced by, or could be produced …
Let us compare productions by the same grammar
“-gr.tryDerivationModes” in all derivation modes. The grammar comprises two subgrammars. The second one (gram#2) uses the ORD derivation mode in all examples. We …
Produce all items

The core of the Bol Processor, in all its versions, is an inference engine capable of generating 'items' — strings of variables and terminal symbols — treated like the score …

Edit extra

Enter notes
Notes can be entered from a connected MIDI device to the Grammar or Data projects of BolProcessor BP3. This is a monophonic input with no timing parameters. For time-tagged MIDI …
Keyboard mapping
The first version of the Bol Processor (BP1) was an advanced word processor designed to store text representations of musical variations created by Indian drum players. This work required a …

Output

Event lists
The Bol Processor can produce detailed lists of sound events as text files. This will facilitate connections with a great diversity of sound devices in replacement of the MIDI and …
Real-time MIDI
In May 2024, the Bol Processor BP3 acquired the ability to manage the input and output of MIDI events. This allows it to "communicate" in real time with external MIDI …

Syntax

Performance controls such as _volume(), _pan(), _mod() (modulation), _press() (pressure) and _pitchbend() modify the sound of the notes and sound-objects that follow them. In MIDI they produce controller messages, and …
Sound-objects
Sound-objects are a specific type of time-objects handled by the Bol Processor. Whereas time-objects are designed to send timely commands to various devices, including robots, sound-objects produce sounds via MIDI …
Serial tools
Examples cited on this page belong to the -da.trySerialTools project. Geeks can check the "Trace serial tools" option in the settings if they wish to monitor processes in Zouleb.c. The …
Silent sound-objects
Silent sound-objects have the same metric and topological properties as simple notes …
Flags can be used in grammars to activate/deactivate rules according to simple numerical and logical evaluations …
Polymetric structures
Polymetric expressions are the basic representation model for the timing of musical data in the Bol Processor …
Tied notes
An algorithm for computing the time intervals of tied notes in Bol Processor BP3 …
Time patterns (smooth time)
A simple grammar illustrating the use of time-patterns in smooth time …

Import-export

AI recognition of polymetric notation
The aim of the current project is to transcribe a musical input (given by a stream of MIDI events) to the most comprehensible polymetric notation …
Importing MusicXML scores
Importing MusicXML scores to Bol Processor BP3 …

Microtonality: how it works

This page is for programmers who want to read, maintain or extend the code that plays notes of microtonal scales. A scale is selected in a score with _scale(name,blockkey), and its notes must then sound at frequencies that do not belong to the 12-tone equal temperament. The page describes how scales are loaded, and how their frequencies reach a Csound score, real-time MIDI and MIDI files.

The two kinds of output follow very different paths:

  • in Csound, each note is a line of the score with its own pitch field. The console simply calculates the frequency of the note and writes it in Hertz (note 4);
  • in MIDI, a note only has a key number (0 to 127) and the pitch can only be changed with a pitchbend message, which applies to a whole channel. The console therefore gives each sounding note a channel of its own, and sends on this channel the pitchbend that corrects the pitch of the key. This mimics MIDI Polyphonic Expression (MPE). The channel is chosen by AssignUniqueChannel() (notes 5 to 9).

The code lives mainly in Tonality.c (scales and frequencies) and MIDIstuff.c (SendToDriver() and AssignUniqueChannel()). A few lines in SaveLoads1.c, CompileProcs.c, CsoundScoreMake.c, MakeSound.c, MIDIdriver.c and Inits.c connect it to the rest of the program.

Comments of the form // note 6 have been placed in Tonality.c and MIDIstuff.c. Each one points to the numbered note of this page that explains the code below it. In the other files, which may contain notes of other pages, the comments have the form // note 6 (microtonality). Searching for // note 6 finds every place that note 6 describes. Line numbers are not given because they change with every revision.

The principle

A microtonal scale is a list of frequency ratios, one for each grade, with a base frequency, a base key and an interval of repetition (most often 2, the octave). These are the arguments of a Csound GEN51 function table:

f2 0 128 -51 numgrades interval basefrequency basekey ratio0 ratio1 ... ratioN

Each scale also has the names of its notes (for instance sa r1 r2 ... in a scale of 22 shruti), and possibly the key numbers of its grades. Scales are stored in tonality resource files (-to), which are read when the project names one (note 1).

When the scale is loaded, the console computes for every key from 0 to 127 a correction in cents: how far the frequency of this key in the scale is from the frequency of the same key in an equal-tempered scale with the same base frequency (note 2). The same table of corrections is used by Csound and by MIDI, so that both outputs give the same pitches.

Loading scales

Note 1 — Reading a tonality file

LoadTonality() (SaveLoads1.c) reads the tonality file named in the project. In the JSON format, LoadTonalityJSON() rebuilds, for each scale, the GEN51 line and the strings of the former format (note names between slashes, key numbers between k, fractions between brackets). The former format is read by LoadTonalityOldFormat(). Both call CreateMicrotonalScale() (Tonality.c), which fills an entry of the array Scale (type t_scale): numgrades, interval, basefreq, basekey, baseoctave, tuningratio, notenames, keys, keyclass and numnotes.

A scale may have more grades than notes: names written • are grades without a note. The array keyclass gives the grade of each note. Ratios are read as decimal numbers, then replaced with the exact fractions when they are given. A line with another GEN number is not a scale and is ignored. A table that does not contain numgrades + 1 ratios is rejected with an error.

Scales are numbered from 1 in the order in which they are read (NumberScales). Scale 0 stands for the equal-tempered scale. In the score, the argument of _scale() is not the number of the scale but the index of its name in the string constants of the grammar; FindScale() (MIDIstuff.c) converts it by comparing the names.

Note 2 — The table of corrections

At the end of CreateMicrotonalScale(), two tables of MAXKEY (128) values in cents are filled for the scale:

  • deviation[key] is the difference between the frequency of the key in the scale, basefreq × ratio × intervaloctave − baseoctave, and the frequency of the same key in an equal-tempered scale built on basefreq and basekey;
  • blockkey_shift[key] is the difference between the ratio of the grade of this key and the nearest equal-tempered semitone.

The correction applied to a key is deviation[key] + blockkey_shift[blockkey]. The block key, the second argument of _scale() (DefaultBlockKey = 60 by default, in the settings), is the note whose frequency stays fixed when scales are changed: the second term shifts the whole scale so that this key keeps its equal-tempered pitch.

The values are stored as integers (short), which gives a precision of one cent. The option “Trace microtonality” of the settings (TraceMicrotonality) displays the table, key by key.

Note 3 — Microtonality in MIDI

The compilation of _scale() (GetPerformanceControl(), CompileProcs.c) sets the global MIDImicrotonality when the output is real-time MIDI, a MIDI file or an event list, and not Csound. It displays “Microtonality mimics MIDI Polyphonic Expression”. Everything specific to MIDI on this page depends on this flag. Csound does not need it.

Csound: calculating the frequency

Note 4 — GetPitchWithScale()

In Csound, there is no channel to manage. Each note is a line of the score, and the instrument receives its pitch in one of its fields. When a note belongs to a scale, CscoreWrite() (CsoundScoreMake.c) calls GetPitchWithScale() (Tonality.c), which returns the frequency in Hertz:

frequency = basefreq × 2^(temp_note / 12) × 2^(temp_octave − baseoctave)   (equal-tempered key)
          × ratio0                                                     (ratio of the base key)
          × A4freq / 440                                               (diapason)
          × 2^(cents / 1200)                                           (pitchbend of the note)
          × 2^(correction / 1200)                                      (deviation of the scale, note 2)

The pitchbend of the note, cents, is the value of _pitchbend() converted to cents with the pitchbend range of the Csound instrument. CscoreWrite() then sets pitch_format to IGNORER: the frequency is written as it is, whatever the pitch format of the instrument (octave point pitch class, octave point decimal or cps) declared in the Csound resource file. The instrument of the orchestra must therefore accept a frequency in Hertz when scales are used. The comment of the score line shows the deviation from the equal-tempered pitch of the same key.

Since each note gets its own frequency, any number of notes of any scales can sound at the same time, and the precision is that of the frequency (3 decimals in the score).

MIDI: one channel for each note

MIDI has no way of giving a note an arbitrary frequency. The console sends the key nearest to the frequency, and a pitchbend message that raises or lowers it by the correction. A pitchbend message applies to all notes of its channel, so two notes with different corrections cannot share a channel. MPE solves the same problem for expressive controllers: the instrument uses a zone of channels, here channels 2 to 16 (the member channels), and each note gets a member channel of its own while it sounds. Channel 1 is the manager channel of the zone and receives no notes. Synthesisers that accept MPE, such as Pianoteq, play these notes correctly. Others work as well, provided they apply the pitchbend of each channel to its notes, which multi-timbral General MIDI synthesisers do.

Up to 15 notes of scales can sound at the same time.

Note 5 — SendToDriver()

Every MIDI event goes through SendToDriver() (MIDIstuff.c), which sends it to real-time MIDI (SendToStack()) or writes it to the MIDI file. With MIDImicrotonality, a NoteOn or NoteOff whose scale is a microtonal scale (i_scale > 0) is processed as follows:

  1. FindScale() gives the number of the scale (note 1).
  2. pitchbend_master is the pitchbend of the sound-object instance at its start (PitchbendStart(), set by _pitchbend()), relative to the centre value 8192. It is added to the correction of the scale (note 9).
  3. AssignUniqueChannel() chooses the channel of the note (notes 6 and 7). The channel of the item, set by _chan(), is ignored.
  4. The status of the event is set to this channel.
  5. For a NoteOn, the correction of the key is computed (note 2), the key may be moved (note 8), and a pitchbend message is sent on the channel before the NoteOn, at the same date (note 9).

Other events (control changes, program changes, pressure…) and notes of the equal-tempered scale (_scale(0,0), or no scale) keep the channel of the item.

Note 6 — AssignUniqueChannel(): NoteOff

The state of channels 2 to 16 is kept in global arrays indexed by the channel number minus 1 (ch = 1 to 15):

  • MPEnote[ch]: the key sounding on the channel, 0 if it is free;
  • MPEscale[ch]: its scale, −1 if the channel is free;
  • MPEpitch[ch]: its pitchbend_master;
  • MPEold_note[ch] and MPEnew_note[ch]: the key requested and the key sent, when they differ (note 8);
  • MPEreleased[ch]: the value of a counter (MPEreleaseCount) when the channel was last released.

They are reset by Inits.c when the console starts.

A NoteOff (or a NoteOn with velocity 0) must be sent on the channel of its NoteOn. AssignUniqueChannel() looks for it in three passes, and stops at the first channel found:

  1. a channel whose MPEold_note is the key, with the same scale and pitch: the NoteOn had been moved to another key (note 8);
  2. a channel whose MPEnote is the key, with the same scale and pitch;
  3. a channel whose MPEnote is the key, with the same scale, whatever the pitch. This pass, added on 2026-10-13, finds notes whose pitchbend has changed between the NoteOn and the NoteOff.

The channel found is released: MPEnote = 0, MPEscale = MPEpitch = −1, and MPEreleased takes the next value of the counter. If no channel is found, the function returns 0, and SendToDriver() displays “No channel available” (at most 5 times) and sends the NoteOff on channel 1. This message reveals a NoteOff without a NoteOn. Such a case was fixed in MakeSound() on 2026-11-13, where a NoteOn merged with the previous one was counted as sounding (see note 28 of the page about MakeSound()).

Note 7 — AssignUniqueChannel(): NoteOn

A NoteOn takes a free channel (MPEnote = 0 and MPEscale = −1), and records its key, scale and pitch. Among the free channels, the one chosen is:

  • the channel released longest ago (smallest MPEreleased). A channel that has just been released still plays the release of its note: the sound continues after the NoteOff, often for a long time with a piano. The pitchbend of the next note would shift the pitch of this release, which makes a click on some synthesisers (heard with Pianoteq). Taking the channel released longest ago leaves the most time to the release. Before 2026-11-16, the first free channel was taken, so that the same channels were used over and over;
  • not channel 10, unless no other channel is free. Channel 10 (ch = 9) is the percussion channel of General MIDI: a player of MIDI files, or a General MIDI synthesiser, plays its notes as drum sounds, whatever the program selected. An MPE synthesiser does not make this distinction, which is why channel 10 is still used as a last resort rather than losing a note. With 14 other channels, this only happens when more than 14 notes of scales sound at the same time.

If all 15 channels are busy, the function returns 0, and SendToDriver() displays “No channel available” and sends the note on channel 1. Its pitchbend then applies to every note sent on channel 1.

Note 8 — Moving the key

The pitchbend corrects a key by less than a semitone in each direction. When the correction of the key is less than −100 cents or at least 100 cents, the note is sent on another key: new_note = note + floor(correction / 100), and the correction is reduced by the same number of semitones, which brings it between 0 and 99 cents. The key requested is stored in MPEold_note[ch] and the key sent in MPEnew_note[ch] and MPEnote[ch].

The NoteOff, which still carries the key requested, finds the channel by MPEold_note (note 6, first pass). SendToDriver() then replaces its key with MPEnew_note, so that the synthesiser releases the key that it plays, and resets both values to −1.

If the new key is out of the range 0 to 127, the error “Microtonality pitchbender out of range” is displayed and the note is sent without correction.

Note 9 — The pitchbend message

The pitchbend value is a 14-bit number, from 0 to 16383, with 8192 (DEFTPITCHBEND) for no bend. The console assumes that the synthesiser has a pitchbend sensitivity of ±2 semitones, the default value of General MIDI. The range ±200 cents then corresponds to ±8192, so one cent is 8192 / 200 = 40.96 units:

pitchBendValue = 8192 + pitchbend_master + correction × 8192 / 200

The value is limited to 0…16383, with an error message (“Pitchbender out of range”) displayed at most 4 times. It is split into two bytes of 7 bits (LSB first), and sent as PitchBend + channel at the date of the NoteOn: to the stack of real-time events with SendToStack(), or to the MIDI file with WriteMIDIbyte(). Since it is sent before the NoteOn, the note starts at the right pitch.

The resolution of the pitchbend is finer than a cent, so the precision of MIDI is the precision of the table of corrections, one cent. With “Trace microtonality”, each note is displayed with its key, name, channel, scale, correction and frequency, in the form § key K: "name" channel C, scale #S (block key B) -> key K2 corr N cents, freq F Hz, where -> key K2 only appears when the key has been moved (note 8).

Note 10 — Volume in MIDI MPE

The volume of a note (_volume()) is normally sent as control change 7 (CC7) on the channel of the item, at the start of the sound-object (SendInitialControls(), MakeSound.c). With microtonality, the notes are no longer on the channel of the item, which is often channel 1, the manager channel of the MPE zone. A synthesiser in MPE mode, such as Pianoteq, applies a control change of the manager channel to all notes of the zone. With -gr.tryShruti, the drone and the melody have different volumes: the volume jumped at each note of either part, changing the loudness of the other one.

Since 2026-11-16, the volume of a note of a scale is applied to its velocity, which belongs to the note alone:

  • VolumeAsVelocity() tells whether a note is concerned: not Csound, MIDImicrotonality, and a microtonal scale;
  • in MakeSound(), before the NoteOn is sent, the velocity becomes velocity × volume / DeftVolume, limited to 1…127, where volume is the volume of the instance (InstanceVolume()) and DeftVolume the default volume of the settings (90). A note at the default volume keeps its velocity. This is not done for a sound-object whose prototype ignores the volume (OkVolume);
  • in SendInitialControls(), the CC7 is no longer sent for these notes.

The MPE specification recommends exactly this: the volume of a single note is expressed by its velocity, or by messages on its own channel (channel pressure, CC74), never by a control change of the manager channel.

Note 11 — MIDI input

When MIDI input is played through to the output (sendMIDIEvent() with direction == INmidi, MIDIdriver.c), the notes received are processed in the same way if a scale is current: the key is shifted by basekey − 60, a channel is assigned with AssignUniqueChannel(), and the correction is sent as a pitchbend. Events produced by the console go through SendToDriver() instead, and are not corrected a second time.

Note 12 — Channel filters

The filters of the MIDI outputs (MIDIchannelFilter, PassOutEvent()) are ignored with microtonality. Since the channel of a note is chosen by AssignUniqueChannel(), filtering channels would drop notes at random.

Note 13 — Event lists

An event list contains notes with their channels, but no pitchbend. When it is the output, the first note of each scale exports the scale as a Scala file (.scl) and a keyboard mapping (.kbm) to the output folder (ExportScale(), ExportSCL(), ExportKBM(), Tonality.c), so that the program reading the list can tune its notes.

Note 14 — Settings sent to the synthesiser

In real-time MIDI, when the diapason (A4freq) is not 440 Hz, TuneMIDIdevice() (MakeSound.c) sends the tuning to all channels (registered parameter 2), and the corrections of the scales do not include it. This is not done in MIDI files.

SetUpMPEreceiver() would configure the synthesiser for MPE (an MPE configuration message for a lower zone of 15 member channels, and a pitchbend sensitivity of ±2 semitones on each channel). It is not called: Pianoteq did not need it, and these messages made unwanted noises when improvising with -gr.Mozart. The synthesiser must therefore be set by hand.

Limitations

  • The pitchbend sensitivity of the synthesiser must be ±2 semitones. The MPE specification gives the member channels a default sensitivity of ±48 semitones: a synthesiser in MPE mode may need to be set accordingly, otherwise every correction is 24 times too large.
  • At most 15 notes of different scales can sound at the same time, 14 without using channel 10.
  • Notes without a scale, or in the equal-tempered scale, keep the channel of the item. If this channel is one of channels 2 to 16, a note of a scale may be assigned the same channel, and its pitchbend then changes their pitch. Such notes are best sent on channel 1.
  • Continuous variations of the volume (_volumecont), and other control changes, are still sent on the channel of the item, which applies them to all notes of an MPE zone (note 10).
  • The pitchbend of a note is fixed at its start. A continuous variation of the pitchbend is sent on the channel of the item, not on the channels of the notes.
  • In MIDI, the diapason is only applied in real time (note 14). In Csound, it is part of the frequency (note 4).

Debugging microtonality

  • The projects -gr.tryShruti, -gr.tryScales, -gr.tryRagas, -gr.tryTunings and -gr.tryOneScale of the sample set use scales. They can be run in a terminal, from the php folder, with the tonality file named in their header, for instance:

    ../bp produce -gr ../ctests_git/-gr.tryShruti -se ../ctests_git/-se.tryShruti -cs ../csound_resources/-cs.tryShruti -to ../tonality_resources/-to.tryShruti --seed 1 --midiout /tmp/shruti.mid

    with --csoundout /tmp/shruti.sco instead of --midiout for Csound.
  • The option “Trace microtonality” (TraceMicrotonality) of the settings displays the table of corrections of each scale (note 2) and every note sent (note 9). For Csound, the same lines are displayed by GetPitchWithScale(), which allows comparing the frequencies of both outputs.
  • In AssignUniqueChannel(), setting the local variable test to TRUE displays each NoteOn and NoteOff with the channel found, and the state of the channels examined.
  • In a MIDI file, each NoteOn of a scale must be preceded by a pitchbend on the same channel, at the same date, and its NoteOff must be on the same channel with the same key.

Note: This page was entirely composed by Claude Opus 5.5 on 16 November 2026.

Real-time Csound: how it works

This page is for programmers who want to read, maintain or extend the code that plays Bol Processor items in real time with Csound. Real-time Csound is an output format next to real-time MIDI, MIDI files, Csound scores and event lists. The page describes how the PHP interface runs a Csound server, and how the console sends it the score while the music is being produced.

The code lives in two places:

  • in the console (source/BP3/), the file CsoundRealTime.c contains everything specific to real-time Csound. A few lines in ConsoleMain.c, ConsoleMessages.c, ConsoleStubs.c, MakeSound.c, ProduceItems.c, Graphic.c and SaveLoads1.c connect it to the rest of the program;
  • in the interface (php/), the file _csoundrt.php starts, checks and stops the Csound server. It is used by produce.php, by the project pages grammar.php and data.php, and by csoundrt_quit.php.

Comments of the form // note 9 have been placed in CsoundRealTime.c. Each one points to the numbered note of this page that explains the code below it. In the other files, which may contain notes of other pages, the comments have the form // note 9 (real-time Csound). Searching for // note 9 finds every place that note 9 describes. Line numbers are not given because they change with every revision.

👉 More pages about Csound in the Bol Processor environment: follow this link.

The principle

The Bol Processor already knew how to write a Csound score: MakeSound() calls CscoreWrite() (CsoundScoreMake.c) for each note or sound-object, and MakeCsoundFunctionTable() (CsoundMaths.c) for the function tables of continuous parameters such as pitchbend or volume. The score is then given to Csound together with an orchestra, and Csound produces a sound file. This is done after the score is complete.

Real-time Csound uses the same score, line by line, while it is being produced. Csound runs as a server: started with option --port=N, it listens to UDP port N of the computer and plays the events it receives on the audio output. The console sends each line of the score shortly before its date, as a real-time score event. Csound starts the event at the time given in its field p2, counted from the moment it receives the message. This places each note to within a control cycle of Csound, whatever the delays of the network and of the operating system, as long as the message arrives before its date.

UDP was chosen because it needs no extra library: the console uses the sockets of the operating system, and Csound has had a UDP server since version 6.14. Messages are sent on the same computer (address 127.0.0.1), where they are not lost in practice. There is no answer from Csound, and no connection to maintain.

A message is a line of text. If it starts with $, Csound reads it as a score event. Otherwise it reads it as orchestra code, which it compiles and runs at once. For example:

  • $f101 0.1482 128 -7 24.000 ... creates function table 101 in 148.2 milliseconds;
  • $i3 0.1482 1.000 440.000 8192.000 8192.000 24.000 21.688 0.000 0.000 0.000 0.000 0.000 starts a note of instrument 3 in 148.2 milliseconds, lasting 1 second;
  • instr BP_stop_all ... endin followed by schedule "BP_stop_all", 0, 0.1 defines an instrument and starts it at once (note 11).

The Csound server, run by the interface

The interface offers the output format “Real-time Csound” (value csoundrt) when a suitable version of Csound is responding (csound_ready()). On the project pages, csoundrt_panel() (_basic_tasks.php) replaces the name of the output file with the name of the orchestra, and tells whether the Csound server is running. Its button QUIT CSOUND calls csoundrt_quit.php. Below it, the MIDI ports of the project are displayed and saved as in real-time MIDI: they are used for interaction (notes 20 and 21).

The server is started by produce.php before it runs the console. It then runs in the background, independently of the console and of the web page. It keeps running between performances, so that the next one starts at once. The constant CSOUND_RT_PORT (_csoundrt.php) gives its port, 10789.

Starting the server

csoundrt_start() makes sure that a server is running with the orchestra of the project. This orchestra is the one named in the Csound resource file (-cs) or in the settings, or 0-default.orc if none is named. The function proceeds as follows:

  1. It asks the server to respond (csoundrt_ping(), see below). If it does, and if the file csoundrt_server.json (in temp_bolprocessor) shows that it was started with the same orchestra, the same version of this file (its date of modification), the same Csound program and the same port, nothing needs to be done.
  2. Otherwise, a server that responds is asked to quit (csoundrt_quit(), which sends exitnow and waits until the port is free). If the port is in use but nothing responds, another program is probably using it, and the function gives up.
  3. Csound is started in the background with csound -odac -d -m0 -+msg_color=0 --port=10789 --orc <orchestra>. Its messages go to temp_bolprocessor/csoundrt_log.txt. On Windows, start /B returns at once and leaves Csound running. On MacOS and Linux, the same is done with nohup … &.
  4. The function waits up to 10 seconds for Csound to respond. It stops waiting as soon as the log shows that Csound has given up (Failed to initialise real time audio output, or the UDP server has stopped).
  5. If the audio output could not be opened, other outputs are tried in turn. If the device does not accept the sample rate of the orchestra (Invalid sample rate, e.g. 44100 Hz on a Windows device working at 48000 Hz), Csound is started again with --use-system-sr, which takes the rate of the device. Csound then adjusts kr so that ksmps remains the same. On Linux, if the default output cannot be opened, the ALSA playback devices listed in /proc/asound/pcm are tried with -+rtaudio=alsa -odac:plughw:card,device (csoundrt_alsa_devices()), analog outputs before HDMI and DisplayPort ones. The reason is that XAMPP runs the server as user daemon. This user belongs to group audio, so it can open the sound card, but the default output goes through PulseAudio or PipeWire, which only serve the user of the desktop.
  6. When Csound responds, csoundrt_server.json is written, with the audio output used. produce.php displays a message if the server has been started or restarted, and the end of the log if it failed.

On Linux, csound_environment() sets the library paths needed by Csound. produce.php restores them afterwards, since the console runs next with the same environment.

Checking that the server responds

UDP gives no answer, so csoundrt_ping() asks Csound for a sign of life: it sends the orchestra code fprints "…/csoundrt_ping.txt", "BP_ALIVE_123456\n" with a random number, and waits until this line appears in the file. Csound keeps this file open, which on Windows prevents deleting it while the server runs. The same file is therefore used every time, and only the random number tells a new answer from an old one. The file is deleted when a new server is started.

csoundrt_port_in_use() is a quicker test, used when the page only needs to know whether something listens to the port: it tries to open the same UDP port, which fails if Csound is using it.

Quitting when idle

A server left running would keep the audio device and use some processor time, for instance with the reverberation instrument of 0-default.orc, which runs all the time. Before each performance, csoundrt_begin_performance() defines two instruments: BP_idle_quit, which runs exitnow, and BP_cancel_idle, which removes the scheduled instances of BP_idle_quit with turnoff3. It starts BP_cancel_idle at once. After the performance, csoundrt_end_performance() schedules BP_idle_quit in CSOUND_RT_IDLE seconds (15 minutes). A new performance cancels it. The next performance after the server has quit starts it again, which takes about one second.

Reporting errors

If the instruments of the Csound resource file do not match the orchestra, Csound may reject notes, for instance when a field that the resource file uses for volume is read by the orchestra as the number of a function table. Before running the console, produce.php notes the size of the log (csoundrt_log_size()). After the performance, it reads the messages written since then (csoundrt_log_since()). csound_errors_summary() counts the notes deleted and groups the errors that differ only by numbers, and csound_errors_report() turns them into a warning displayed on the page. The same is done with Csound's messages when a Csound score is converted to a sound file. The console displays the orchestra named in the resource file (note 19), and produce.php adds the name of the orchestra used to the console's messages.

The console

The console builds the score exactly as it would for a file. The only differences are where its text goes, and the time it takes: the console waits for the music, so that it never runs ahead of it by more than one item.

Note 1 — The option --csoundrt

produce.php runs the console with --csoundrt 10789 instead of --csoundout file. ParsePostInitArgs() (ConsoleMain.c) sets the globals CsoundRT and CsoundRTport, and sets opts->writeCsoundScore, so that ApplyArgs() sets OutCsound, the flag of Csound output, which makes MakeSound() write the score (cswrite) instead of sending MIDI events. At the end of the arguments, CsRTOpen() is called.

If the MIDI ports of the project have been saved, produce.php adds --rtmidi. The MIDI system is then started as in real-time MIDI, with the inputs and outputs of the file _midiport, but it is only used for interaction (notes 20 and 21): notes are still played by Csound. If MIDI cannot be started, for instance because no MIDI output is available, or because no trace path (--traceout) gives the name of the _midiport file, the console displays a warning and real-time Csound plays without MIDI, whereas real-time MIDI would stop. --csoundout can be given as well: the same score is then written to a file, which is useful for testing (see “Debugging” below).

Note 2 — Opening the socket

CsRTOpen() creates a UDP socket and the address 127.0.0.1:port. On Windows, the sockets library is started first with WSAStartup(). The Makefile already links ws2_32, which libcurl needs, and curl.h includes winsock2.h before -BP3.h includes windows.h, which is the order Windows requires. The queue and the other variables of the performance are reset.

Note 3 — A score without a file

MakeSound() calls PrepareCsFile() (ConsoleStubs.c) before writing the first item. This function used to require the name of a score file. With CsoundRT, MakeCsoundScoreFile() may now open no file: CsScoreOpened and CsRefNum are set as usual, so that every function writing the score works unchanged. The header of the score is written as usual too, in particular the function tables of the Csound resource file (f1 0 256 10 1…), which reach Csound before the first note.

Note 4 — Capturing the score

Every piece of the score is written by WriteToFile() or NoReturnWriteToFile() (SaveLoads3.c) with destination CsRefNum, i.e. odCsScore. Both call BPPrintMessage() (ConsoleMessages.c). With CsoundRT, BPPrintMessage() passes the text for odCsScore to CsRTText(), then to the score file if there is one. This single connection catches everything: the lines of CscoreWrite(), which are written in several pieces (the instrument, then each field), the function tables, the silences added between items, the tempo statements and the comments.

CsRTText() formats the text and appends it to a buffer, CsRTPending. Each complete line (ending with a line feed) is given to CsRTLine(). What remains is kept until the next call.

Note 5 — Selecting and reading lines

CsRTLine() removes the comment (from ;) and the spaces at both ends. Only i (instrument) and f (function table) lines are kept. The others are not sent to Csound:

  • t (tempo) lines: the Bol Processor always writes a tempo of 60, so that dates are in seconds;
  • s (section) and e (end) lines, which have no meaning for a server that keeps running, and could even stop it;
  • comments and empty lines.

The line is split into a head, the letter and field p1 without spaces (e.g. i3 or f101), its date p2, and the rest, the fields after p2, kept as they are. The form i 3 …, which may be found in the tables of a resource file, is accepted. For an i line, the integer part of p1 is added to the list of instruments used (CsRTInstruments, at most CSRT_MAXINSTR), which note 11 needs, and the end of the note (p2 + p3) updates CsRTLastEnd, the end of the performance (note 13).

Note 6 — The queue

Lines wait in CsRTQueue, sorted by date. CsRTPush() inserts each new line after the lines of the same date or earlier. Lines are not always written in the order of their dates, since MakeSound() deals with the sequences of a polymetric structure one after the other. But the order of lines of the same date is kept, which matters: MakeCsoundFunctionTable() writes the table of a note before the note, and Csound runs events of the same date in the order received, so that the note finds its table. Since most lines arrive in order, the insertion point is searched from the end of the queue.

The same function adds lines to CsRTSent, the lines that have been sent and have not started yet (note 12), without sorting.

Note 7 — Pacing the items

At the end of each item, MakeSound() calls CsRTFlush(TRUE). The lines of the item are all in the queue, since computing and writing an item takes much less time than playing it. CsRTFlush() then sends them in time (note 9), checking every 2 milliseconds, and returns when the queue is empty, i.e. when the last line of the item has been sent, CSRT_LOOKAHEAD seconds before its date. MakeSound() then returns, and the next item is computed while the last notes of this one are sounding.

The dates of the score continue from one item to the next: in improvisation, when playing all items or all chunks, MakeSound() starts each item at LastTime, the end of the previous one, and so do the lines of a data item played one after the other. The real-time performance therefore reproduces the score file exactly, as long as the next item is ready before its first date (note 10).

CsRTFlush() is also where stop, panic, pause and continue are handled (notes 11 and 12), since the console spends most of a performance in it.

Note 8 — The time origin

The performance is placed on the clock of the computer (getClockTime(), in microseconds) by CsRTOrigin, the clock time of date 0 of the score: a line of date t must start at CsRTOrigin + t. CsRTOrigin is set at the first call of CsRTFlush() that finds lines in the queue, i.e. when the first item has been computed. It is the current time plus CSRT_LATENCY (0.3 second), which leaves time to send the first lines in advance. If the first date is negative, which may happen with sound-objects that start before their beat (pre-roll), the origin is moved later accordingly. CsRTDateToClock() converts dates, including negative ones, to clock times.

Note 9 — Sending the lines in time

CsRTSendDue() sends every line of the queue whose date is less than CSRT_LOOKAHEAD (0.15 second) away. Since the queue is sorted, it stops at the first line that is not due. For each line, it computes the delay between now and its date, and sends $, the head, the delay with 4 decimals, and the rest: $i3 0.1482 1.000 440.000 …. The original date is thus replaced with a delay, the only form Csound understands for real-time events. Csound starts the note when this delay has elapsed after it received the message, at the precision of a control cycle (ksmps samples: 10 samples at 44100 Hz with 0-default.orc).

Sending in advance makes the timing independent of the delays of the console: the moment at which the message is sent does not matter, as long as it is less than 0.15 second late. Measured on MacOS, notes started within 2 milliseconds of their dates, compared with the score of the same performance.

CsRTSend() sends one message with sendto(). A message that cannot be sent produces an error message, at most 5 times in a performance. With the trace option of Csound in the settings (CsoundTrace), each message is displayed (Csound <- …).

Each line sent is moved to CsRTSent with its date, until it has started (note 12). Lines that have started are removed from CsRTSent at the next call.

Note 10 — Late lines

A line is late if its date has passed when it is sent: the delay is negative. This happens when computing an item took longer than the remaining notes of the previous one, or when the console has been held up by the system. The line is then sent with delay 0, and CsRTOrigin is moved later by the same amount. All later lines are shifted too, so that the rest of the music keeps its rhythm, with a gap instead of a rush of late notes. The performance clock (note 14) is shifted as well.

Note 11 — Stop and panic

At each turn of its loop, CsRTFlush() calls stop() (ConsoleMain.c), as real-time MIDI does. This function checks, at most every 500 milliseconds, the files created by the buttons STOP, PANIC, PAUSE and CONTINUE of the interface. If it returns something other than OK, CsRTPanic() empties the queue and the list of lines sent, and calls CsRTStopAll(), and CsRTFlush() returns the same code to MakeSound().

CsRTStopAll() turns off the notes of the instruments used (note 5), and only these, so that instruments of the orchestra that run all the time, such as the reverberation of 0-default.orc, are not affected. It sends orchestra code defining an instrument BP_stop_all, which runs, for each instrument n used:

  • turnoff3 n, which removes the notes of instrument n that Csound has received and not started yet, i.e. those of the last 0.15 second (note 9);
  • turnoff2 n, 0, 1, which turns off its notes that are sounding, allowing their release, so that their envelopes end smoothly;

then turnoff, which ends BP_stop_all itself. The code ends with schedule "BP_stop_all", 0, 0.1, which starts it at once. turnoff3 must run inside an instrument: in global code, run once when it is compiled, it has no effect on scheduled notes. Redefining BP_stop_all each time is accepted by Csound.

Note 12 — Pause and continue

A pause is requested in two ways: the PAUSE button, whose file sets PausePlay when stop() finds it, and a MIDI Stop message received from another device or another instance of the Bol Processor, if the setting Respond to Stop/Continue (StopPauseContinue) is on. In the latter case, as in real-time MIDI, HandleInputEvent() (MIDIstuff.c) sets StopPlay and sends All Notes Off to the MIDI outputs, and a MIDI Continue message resets StopPlay. When PausePlay or StopPlay is set, CsRTFlush():

  1. calls CsRTStopAll(), which stops the sounding notes and removes those that Csound has received and not started yet;
  2. puts back in the queue the lines of CsRTSent, i.e. those removed in Csound by turnoff3, so that they will be sent again;
  3. waits, checking every 20 milliseconds, until stop() finds the file of CONTINUE, or a MIDI Continue message is received (or until the STOP or PANIC button is clicked);
  4. moves CsRTOrigin later by the duration of the pause.

The music thus resumes where it stopped. Notes that were sounding are not resumed in the middle: they have been released when the pause began.

Note 13 — The end of the performance

When the work is over, main() (ConsoleMain.c) calls CloseCsScore() (ConsoleStubs.c), which writes the end of the score and closes its file if there is one, then calls CsRTEnd(). This function processes the text left in CsRTPending, sends the remaining lines (CsRTFlush(TRUE)), and waits until CsRTLastEnd, the end of the last note. The console therefore runs as long as the music: the page of produce.php shows that it is working, and its STOP button works until the end. In the meantime, a pause is still possible. After a stop or a panic, CsRTEnd() only turns off the notes. After a normal end, it displays the duration of the performance and resets the variables of the performance, so that a later score starts afresh.

Note 14 — The performance clock

The page of produce.php displays the date of the performance, which the console writes every 200 milliseconds to the file _time (WriteTimeFile(), ConsoleMain.c), with the expected end. With CsoundRT, both are given by CsRTDate(): the date is the clock time minus CsRTOrigin, which takes account of pauses and late lines, and the end is CsRTLastEnd, the end of the last note written so far. WriteTimeFile() is called by stop(), which CsRTFlush() calls at each turn of its loop. When the performance is stopped, the file keeps the date at which it stopped, which produce.php displays.

Note 15 — No limit of items

When the output is a file, the number of items produced in improvisation is limited by the setting MaxItemsProduce (20 by default). Like real-time MIDI, real-time Csound has no limit: improvisation continues until it is stopped. This concerns MakeSound(), ProduceItems() (ProduceItems.c) and DrawItem() (Graphic.c). If a score file is written as well (--csoundout), its size is still limited by MaxOutputFileSize.

Note 16 — Closing

main() calls CsRTClose() after CloseCsScore(). It closes the socket (and calls WSACleanup() on Windows), and frees the queue, the list of lines sent and the buffer of text. The Csound server keeps running.

Note 17 — Waiting

The loops of CsRTFlush() and CsRTEnd() wait with CsRTSleep(), which calls Sleep() on Windows and usleep() elsewhere. The function mysleep() (Misc.c), used elsewhere in the console, is a busy loop on Windows, which would keep a processor busy during the whole performance. The resolution of Sleep() may be as coarse as 15 milliseconds on Windows. This does no harm, since lines are sent 0.15 second in advance and their delay is computed when they are sent.

Note 18 — Long lines

The function tables of continuous parameters may give long lines. On MacOS, a UDP message cannot exceed 9216 bytes by default, so CsRTOpen() sets the size of the sending buffer to 64 kilobytes (SO_SNDBUF). Messages of more than 52000 bytes have been received by Csound in tests. A message cannot exceed about 65500 bytes in UDP, so CsRTSend() refuses those longer than CSRT_MAXMESSAGE (65000 bytes) and displays an error.

Note 19 — The orchestra of the resource file

When it loads a Csound resource file, the console displays the number of instruments found, and now the name of the orchestra named in this file (CsoundOrchestraName), or that none is named. This is done in LoadCsoundInstrumentsJSON() and LoadCsoundInstrumentsOldFormat() (SaveLoads1.c). The instruments of the resource file describe the fields (p-fields) of the score, which must be the ones expected by the instruments of the orchestra. The orchestra actually used is chosen by the interface, and may differ (see “Reporting errors” above).

Note 20 — Waiting, holding and MIDI messages

Script instructions such as _script(wait for C3 channel 1), _script(Hold for 1500 milliseconds) or _script(MIDI send Start) are registered by MakeSound() while it writes the item, with the date of the object they are attached to (in microseconds). Read Interactions in MIDI and Csound.

Waits go to the table p_INscript (instructions 46 Space, 47 forever, 97 a note, 66 Continue, 67 Start, 128 Stop), holds and MIDI messages to p_OUTscript (instructions 17, 190, 191, 192). In real-time MIDI, check_stop_instructions() (MIDIstuff.c) executes them on the timeline of MIDI events, which TimeStopped shifts after each wait. Real-time Csound has its own timeline, the dates of the score placed by CsRTOrigin (note 8). CsRTScripts(), called at each turn of the loops of CsRTFlush() and CsRTEnd(), therefore does the same work on this timeline:

  • a hold moves CsRTOrigin later by its duration;
  • MIDI Start, Continue and Stop are sent to the MIDI outputs at once (sendMIDIEvent()), if MIDI is running;
  • a wait sets StopPlay, displays what it is waiting for, and waits, checking stop() every 10 milliseconds, until the MIDI input handler resets StopPlay. The performance then resumes at the date of the script, MIDIsyncDelay milliseconds (a setting) after the event: CsRTOrigin is set so that this date falls at that moment. Notes that were sounding go on during the wait.

Since lines are sent 0.15 second in advance, notes after a wait or a hold would have reached Csound before the wait began. CsRTBarrier() returns the earliest date of a pending wait or hold, and CsRTSendDue() (note 9) keeps in the queue the lines dated at or after it, until it is over.

The MIDI input handlers, HandleInputEvent() (MIDIstuff.c) for notes and StopWaiting() (ConsoleMain.c) for Start, Continue, Stop and the space bar, accept an event only if the date of the performance has reached the date of the script. With CsoundRT, they take this date from CsRTScriptTime(), and they don't add MIDIsyncDelay to TimeStopped, which real-time Csound doesn't use. As in real-time MIDI, a note that ends a wait also ends the other waits of the same date. Without MIDI input, a wait for a MIDI event can only be ended by the STOP button, and a warning says so.

This process can be checked on the -da.tryWait data project.

Note 21 — MIDI running with real-time Csound

With --rtmidi, rtMIDI is true during a real-time Csound performance. In MakeSound(), cswrite is set whenever CsoundRT is true, so that notes go to the Csound score, and the MIDI events that real-time MIDI sends whatever the notes are not sent: the Active Sensing message at the end of each item, and the two silent NoteOns that mark a silence between items. Their timing belongs to real-time MIDI: with no MIDI event in its buffer, MIDIflush() is never called, so check_stop_instructions() does not interfere with CsRTScripts(). The MIDI input filters work as in real-time MIDI, for instance to route events of the keyboard to a MIDI output.

Note 22 — Silent MIDI notes for synchronisation

With --rtmidi, notes of duration 0 are also sent to the MIDI outputs as a NoteOn of the same key and channel with velocity 0. These are mainly out-time notes, written <<C0>>, which the Bol Processor uses as synchronisation signals: for instance {_vel(0) <<C0>>} in -da.trySend, which _script(wait for C0 channel 1) waits for in -da.tryReceive. Csound receives their line too, with p3 = 0, and plays nothing. A NoteOn with velocity 0 is not audible, but it marks a date, so that MIDI devices or another instance of the Bol Processor can synchronise with the performance. The input handlers of the console accept these messages, for instance to end a _script(wait for …) (note 20). Other notes are not sent to MIDI, which would double the flow of events for no use.

When CscoreWrite() (CsoundScoreMake.c) writes the line of a note whose duration (p3) is 0, it calls CsRTMidiNote() with the key, the channel, the instance and the date of the line (p2). Lines of sound-objects defined by their own Csound score (LINE) have no key and are not concerned. The message waits in CsRTMidiQueue, sorted by date. CsRTSendMidiDue(), called at each turn of the loop of CsRTFlush(), sends it with sendMIDIEvent() when its date has come, so that the output filters of the project apply. Unlike Csound lines, it is not sent in advance: it reaches the MIDI output at the date at which Csound starts the note, within about 2 milliseconds on MacOS. Messages dated at or after a pending wait or hold are kept until it is over, like Csound lines. CsRTFlush(TRUE) waits until both queues are empty, i.e. until the date of the last note of the item, so the next item is computed while this note is sounding. After a stop or a panic, the queue is emptied.

On MacOS, CoreMIDI delivers a NoteOn with velocity 0 as a NoteOff with velocity 64, which MIDI considers equivalent. The input handlers of the console only compare the key and the channel of the note, so both forms end a wait.

Limitations

  • The port is fixed (CSOUND_RT_PORT, 10789). If another program uses it, the page says so, and the constant must be changed.
  • Only one server runs at a time. Two projects played at the same time with different orchestras restart the server in turn, which interrupts the other performance.
  • The timing of a performance relies on the clock of the computer, and that of the notes on the clock of the audio device. Both are accurate enough for the length of an item. Since lines are sent 0.15 second in advance, a drift between the two clocks would never accumulate.
  • A pause releases the notes that are sounding. They are not resumed in the middle when the performance continues.
  • Script dates are kept in unsigned long microseconds, as in real-time MIDI. On Windows, where this type has 32 bits, waits and holds would fail in a performance longer than 71 minutes.
  • Csound does not tell the console whether a note has been played. Errors are only found afterwards in its messages (see “Reporting errors” above).
  • On Linux, an ALSA device cannot be opened while PulseAudio or PipeWire is using it, which they do while another application plays sound. They release it a few seconds after the last sound. While Csound uses the device, the sounds of other applications cannot be played. The alternative would be to run the server as the user of the desktop, which would require a sudo rule in the installation script.

Debugging real-time Csound

  • The console can be run in a terminal, from the php folder, with a Csound server started by hand: csound -odac --port=10789 --orc ../csound_resources/0-default.orc, then for instance ../bp produce -gr ../ctests_git/-gr.checkAllCsound -se ../ctests_git/-se.checkAllCsound -cs ../csound_resources/-cs.checkAllCsound --csoundrt 10789. Csound's option --udp-echo displays every message it receives.
  • Adding --csoundout file.sco writes the same score to a file. The messages sent must be the i and f lines of this file, in the order of their dates, with the dates replaced by delays. Instead of Csound, a small program listening to the UDP port can record each message with the time it arrives: the time of arrival plus the delay must give the dates of the score, shifted by a constant.
  • The trace option of Csound in the settings (CsoundTrace) displays each message sent (note 9). The option Trace MIDI interactions (TraceMIDIinteraction) displays the script instructions registered and the MIDI events received (note 20).
  • Waits can be tested without a keyboard: a small program creating a virtual MIDI source (CoreMIDI on MacOS, ALSA on Linux) can send notes at given times. Its port number must then be given in the _midiport file, since the console finds inputs by number before name.
  • The messages of the server are in temp_bolprocessor/csoundrt_log.txt, and its state in temp_bolprocessor/csoundrt_server.json. The server runs with -m0, which displays errors but not the amplitude of each note. Starting it by hand without this option shows every note.
  • Rendering the score file with Csound (csound -n orchestra file.sco) gives the same errors as the real-time performance, if the instruments of the resource file do not match the orchestra.
  • The regression test run-ctests.sh checks the Csound scores, which real-time Csound sends unchanged. It does not run a real-time performance.

Note: This page was entirely composed by Claude Opus 5.5 on 16 November 2026.

« Translate