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.

aaa

Bol Processor BP3 logo

You have just installed the Bol Processor. Welcome! This page is a guided tour for your first hour with it. You will play some music, look at how it is written, and change a few things to hear what happens. No programming skills are needed.

In a few words, the Bol Processor creates music from texts. A text can be:

  • a score that tells exactly what to play, written in a compact notation. These texts are stored in Data projects;
  • a grammar, i.e. a set of rules that build musical pieces step by step, often with a share of chance. These are Grammar projects.

The music can be heard as a MIDI file (with the built-in player), sent in real time to a MIDI instrument, or turned into a Csound score that produces a sound file. You can also import existing music from MusicXML scores.

👉 The sections are meant to be read in order, but you can skip any of them. Each one ends with links to the pages of the Tutorials and Examples menus that take you further.

Before you start

If the Bol Processor is not yet installed, follow the instructions on the Install BP3 page for MacOS, Windows or Linux. Csound is optional: you can install it later.

  • Start your Apache/PHP server (MAMP or XAMPP) and point your web browser at http://localhost/bolprocessor/php/ (note "http", not "https"). If you are using the standalone "BolProcessor.app" on MacOS, just start it.
  • The home page checks your installation and tells you if something is missing. When everything is fine, it says that the console is "responding". The console is the program that actually computes the music; the pages you see in your browser are its interface.
  • Click the "ctests" link. This folder contains all the examples used on this page. The name of each file tells its type: "-da.…" for a Data project, "-gr.…" for a Grammar project, "-se.…" for its settings, etc.

👉 Feel free to modify the examples. The "ctests" folder is restored to its original state each time you update the Bol Processor. For the same reason, keep your own work in another folder (see below).

👉 The interface can be displayed in dark or light mode: use the icon in the top right corner.

Home page of the Bol Processor interface
The home page when the console is installed and responding

Your first sound: a Data project

In the "ctests" folder, click "-da.acceleration". This is a Data project: a text containing one or more musical items written in Bol Processor notation. This one contains a single item:

_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 .

Let us read it before listening:

  • E2, D2, F#2, Bb2… are simple notes in the English convention (C, D, E…). The Italian/French (do, re, mi…) and Indian (sa, re, ga…) conventions are also available.
  • Words starting with an underscore are performance controls. _transpose(12) raises all the notes by one octave (12 semitones), and _vel(60)… _vel(90) set the velocity, i.e. how hard the notes are struck. Here the music gets louder little by little.
  • The periods "." cut the line into beats of equal duration. The first beat contains one note, the second beat two notes, the third beat three notes, and so on until twelve notes. Since all beats last the same time, the notes become shorter and shorter: we hear an acceleration, although no duration is written in the score!

This shows the spirit of the Bol Processor notation: you describe the structure of the music, and the machine works out the exact timings.

Play it as a MIDI file

  • Below the text, the interface shows the item(s) it has found, each with a PLAY button. Click it.
  • A "BP console" window opens. When the console has finished, it shows a MIDI player: click it to listen. A link is also given to download the MIDI file, which is saved in the "my_output" folder.
  • Click the Image link at the top of this window. It displays the notes on a time line, where you can see them getting shorter and shorter.

👉 Some MIDI players need an Internet connection to load their sounds. If you hear nothing, check your connection.

Try this: delete all the periods, click SAVE, then PLAY again. Now all notes have the same duration and the acceleration has disappeared. Put the periods back (or use your browser's Undo) and save again.

Play it in real time

If your computer is connected to a MIDI instrument, or to a software synthesiser, you can send the music to it directly. Above the text, select Real-time MIDI among the output options, save this choice, and click PLAY. The sound quality now depends on your instrument, and the music starts without delay. Read the Real-time MIDI page to set up your MIDI inputs and outputs.

Play it with Csound

If you have installed Csound (version 7 or later), the interface tells you that Csound is responding. Select Csound score as the output option and click PLAY. The console writes a Csound score, then Csound turns it into a sound file that you can hear in the audio player. As no particular instrument is specified here, a simple default instrument ("0-default.orc") is used. We will come back to Csound further down.

Finally, select MIDI file again for the next steps.

👉 Did you notice the "-se.Visser2" and "-gr.acceleration" lines at the top of the data? The first one is a settings file (tempo, note convention, graphics, etc.) used to play this data. The second one is the grammar that composed this item… which brings us to grammars.

A Grammar project

A grammar is a set of rules. Each rule says that a symbol on its left side can be replaced with what is on its right side. Starting from the symbol S, the machine applies rules again and again until only musical elements (notes, rests, sound-objects…) remain. The result is a musical item. Composers use grammars to describe the construction of a piece rather than the piece itself.

Open "-gr.Ames" in the "ctests" folder:

-se.Ames
-cs.tryTunings

// A grammar illustrating the construction of a rather
// complex time structure with an undetermined rest.

ORD
_mm(60.0000) _striated

gram#1[1] S --> _ins(1) {PA, _rest PB}

gram#1[2] PA --> {2,- PA1, 2 PA2} {4,PA3}
gram#1[3] PA1 --> {2,F#3}
gram#1[4] PA2 --> {1,F5,A5}
gram#1[5] PA3 --> PA31 PA32
gram#1[6] PA31 --> {1/2,G#3,E5,G5}
gram#1[7] PA32 --> {7/2,Bb4}

gram#1[8] PB --> {1/4,G#5&,C6,E6,B6&} {2,&G#5,&B6}

Some useful comments:

  • Related files. The first lines name the files this grammar needs: settings "-se.Ames" and Csound instruments "-cs.tryTunings". The interface finds them and shows buttons at the bottom of the page to open them.
  • Comments. Lines starting with // are ignored by the machine. Use them to explain your work.
  • Variables and terminals. S, PA, PB, PA1… are variables: they are rewritten by the rules and disappear from the final result. Notes such as F#3 or Bb4 are terminal symbols: they stay and are played.
  • Rule numbers. "gram#1[3]" means "rule 3 of subgrammar 1". You don't need to type these numbers: click COMPILE GRAMMAR and the interface numbers (or renumbers) the rules for you. Compiling also checks the grammar and reports errors, such as a symbol that is neither a variable nor a known terminal.
  • ORD means that rules are tried in the order they are written. In this grammar each variable has a single rule, so it always produces the same item. Other grammars choose between several rules at random, so each production is different: see the Derivation modes page.
  • _mm(60.0000) sets the metronome to 60 beats per minute, and _striated says that the music follows this regular beat.
  • Curly brackets { } contain polymetric expressions: several voices played together, separated by commas. In {1/2,G#3,E5,G5}, the number before the first comma is the duration (half a beat), and the three notes form a chord. In {2,- PA1, 2 PA2}, the hyphen - is a silence of one unit, and the number 2 placed before a voice is a silence of two units. Each voice is then stretched or compressed to fit the duration given at the start, here 2 beats. See the Polymetric structures tutorial.
  • _rest is an undetermined rest: you don't say how long it lasts, and the machine calculates it. Here, voice PA lasts 6 beats and PB lasts 2¼ beats, so the rest before PB is set to 3¾ beats and both voices end together. Read the Undetermined rests in dance performance page for a real-life use.
  • The ampersand & ties notes: G#5& … &G#5 is a single G#5 that keeps sounding across the two expressions. See Tied notes.
  • _ins(1) selects instrument 1 of "-cs.tryTunings". It is used when the output is a Csound score.

Now click PRODUCE ITEM(s). The console window shows the item that has been produced, after all variables have been replaced:

_ins(Plucked_string1) {{2, - {2, F#3}, 2 {1, F5, A5}} {4, { 1/2 ,G#3, E5, G5} { 7/2 ,Bb4}}, _rest { 1/4 ,G#5&, C6, E6, B6&} {2, &G#5, &B6}}

Listen to it on the MIDI player, then click the Image link to see how the two voices are placed in time.

👉 A common mistake: the note convention must match the way notes are written. "-se.Ames" uses the English convention (C, D, E…). If you change it to Italian/French, "F#3" is no longer recognised as a note and the production fails. The current convention is displayed on the grammar page, and you can convert all notes of a grammar to another convention with a single click at the bottom of the page.

👉 When a production fails, the console window displays the error messages and gives a link to a file with the details.

To go further: the beginner's tutorial builds grammars step by step. The examples of Harm Visser include "-gr.acceleration", the grammar that produced our first item.

Help messages

You don't need to remember all the performance controls and keywords. At the bottom of the "-gr.Ames" page, click SHOW HELP ENTRIES. The grammar is displayed again, with links on all reserved words. Click "_rest": a window opens on the help entry for this word. The same button is available on Data pages.

The complete help file can also be read here.

Help entries displayed on a grammar
Displaying the help on reserved words in a grammar

Try the same with "-gr.Visser.Waves", another grammar by Harm Visser. Produce its item and compare its rendering in MIDI with this one, played on physical-model instruments (read explanations):

“Waves” by Harm Visser (1998), played on physical-model saxophone and piano

Create or import data

The "ctests" folder is a place to experiment, but it is restored during each update. Keep your own work in your own folders (also called workspaces).

Buttons for creating and importing files
  • On the page of a folder, the CREATE FILES OR FOLDERS button opens a form to create a new folder or a new project. Just type a name: the interface adds the right prefix or extension. For example, a grammar called "mygrammar" is saved as "-gr.mygrammar" or "mygrammar.bpgr", as you prefer.
  • IMPORT FILES copies files from your computer into the current folder. Only files used by the Bol Processor are accepted, and they get the access permissions the interface needs.
  • DOWNLOAD FILES lets you take your projects to another computer, and MOVE moves files between folders.
  • Project pages (Data or Grammar) also have download and upload buttons. You can only replace a project with one of the same type, and the replacement can be undone until you save the page.
Download and upload options on a grammar page
Download and upload options on a grammar page

👉 Please don't move files in or out of these folders with the Finder or the File Manager: this can lead to permission errors. If you want to keep your data outside the Bol Processor folder, read the Move data page.

Import MusicXML scores

You can also start from existing music. MusicXML is a standard format for sheet music. Many scores can be downloaded in this format, and score editors such as MuseScore can export it. The Bol Processor converts these scores to its own notation, so you can play them, analyse them, or reuse their fragments in your own grammars.

  • Create a new Data project in one of your folders and open it.
  • At the top of the page, next to Import MusicXML, choose a file and click ← IMPORT. To try, you can take one from the "ctests/xmlsamples" folder.
  • The interface shows the parts of the score and lets you choose which ones to import. The result is a set of polymetric expressions that you can play like any other data.

Below is Beethoven's Fugue in B flat major imported from MusicXML. It shows both the accuracy of the conversion and the complexity of the music that the Bol Processor can handle:

Beethoven's Fugue in B flat major played by the Bol Processor and Csound, with a “Sauveur” temperament ➡ Image
👉 Listen in stereo!

All the details are on the Importing MusicXML scores page. Two famous works are discussed on The Well-tempered Clavier and Bach well-tempered tonal analysis. Music can also be entered from a MIDI keyboard: see Capture MIDI input (work in progress).

Change the start string

A grammar normally starts its work from the symbol S. But you can start from any other variable, to listen to just one part of the construction.

Variables of -gr.Mozart displayed as buttons
Grammar "-gr.Mozart" with its variables at the bottom
  • Open "-gr.Mozart". It is a version of Mozart's musical dice game, in which the variables stand for short musical fragments assembled by chance.
  • At the bottom of the page, the interface lists all the variables as buttons. Click one of them to produce an item starting from this variable.
  • Variables A1 to B8 are chosen at random, so they give a different result each time. Variables T1 to T176 are fixed fragments, so they always sound the same.
  • You can also type a polymetric expression in the field at the bottom, for example {{2,sol3,si3}-,fa5 re5 si4}, and click PRODUCE ITEM. The expression may contain variables. Note that this grammar uses the Italian/French note convention (do, re, mi…).

👉 The settings of this grammar have the Non-stop improvize option checked. Set the output to Real-time MIDI and click PRODUCE ITEM(s): the dice game plays forever, with a new piece each time! Click STOP or PANIC to end it.

Play data

Open "-da.checkPoly". This Data project contains many short items that show the possibilities of polymetric expressions.

Data page with its items
Data project "-da.checkPoly", with the items found by the interface
  • The interface finds every item in the text and shows it with its own buttons. Items are separated by blank lines, so an item can take several lines, for example a title in square brackets above the music. Lines starting with // are comments.
  • PLAY plays the item with the output you have chosen (MIDI file, real-time MIDI, Csound score…).
  • EXPAND shows the item written out in full, with every duration made explicit. It is a good way to understand how the machine reads polymetric expressions.

To learn more about this notation, read Polymetric structures, Tied notes and Carrying over controls.

Sound-object prototypes

So far we have played simple notes. The Bol Processor can also play sound-objects: small pieces of music, such as a drum stroke, a chord or a melodic ornament, that are given a name and used like notes. Their name comes from the bols, the spoken syllables of tabla drumming, which were the first application of the Bol Processor.

The content of sound-objects is stored in sound-object prototype files ("-so.…"). An alphabet file ("-al.…") lists the names that a grammar may use.

Page of a sound-object prototype file
The page of a sound-object prototype file
  • Open "-so.abc1" in the "ctests" folder. Below the horizontal line is a table of its sound-objects: a, a', b, chik, cycle1… These objects are used by the grammar "-gr.koto3", presented on the Interactive improvisation with sound-objects page.
  • Click the button "chik" to open this object. Its PLAY button lets you hear it: it is a chord of three notes. You can also play a combination of objects typed in the form.
  • Each object has parameters that tell the machine how to place it in time: can it be shortened or stretched? Can it overlap with its neighbours? Can it be moved slightly? These are explained on the Sound-objects page.
  • Objects can be created, duplicated or deleted. Try a couple of DELETE buttons: a RESTORE ALL DELETED OBJECTS button appears to undo it. If you create an object, also add its name to the alphabet file.
  • Changes are saved automatically every 30 seconds (see Autosave).

To go further: Sound-objects, Silent sound-objects, and Time-setting of sound-objects for the algorithm.

Csound

Csound in the Bol Processor environment
Csound in the Bol Processor environment

Csound is a free program that creates sounds from two texts: an orchestra, which describes the instruments, and a score, which lists the notes to play. The two programs complement each other: the Bol Processor deals with musical structures and writes the score, and Csound deals with sound.

With Csound, you are no longer limited to the 128 keys and the instruments of MIDI. You can use any tuning or temperament (see Microtonality), and design your own instruments.

  • Open "-gr.Mozart" in the "ctests" folder and select Csound score as the output option.
  • If Csound (version 7 or later) is installed, the interface finds it and says that it is responding. Otherwise, it suggests installing it.
  • Click PRODUCE ITEM(s). The console writes the score "Mozart.sco" in the "my_output" folder, then Csound creates a sound file that appears on an audio player. Click Read the output file to see the score.
Csound score produced by -gr.Mozart
Csound score produced by grammar "-gr.Mozart"

Each line starting with "i" is a note. Its first fields are the instrument number, the start time and the duration (in beats), then the pitch. The following fields carry the volume and other parameters that can change during the note. The name of the note is given as a comment at the end of the line.

Variations on "-gr.Mozart" played by Csound with the "0-default.orc" orchestra, tuned in Zarlino's meantone temperament

A just-intonation version of the dice game can be heard on the Just intonation: a general framework page. All the Csound features are described in Csound in BP3, in particular Csound checkup, Csound objects and Csound tuning in BP3.

Csound instrument files

The Bol Processor can turn MIDI-style controls ("pitchbend", "modulation", "volume", etc.) into parameters of Csound instruments, and it can also handle parameters that have no MIDI equivalent. The orchestra can then make these parameters vary smoothly during a note, using the GEN07 (linear interpolation) or GEN08 (cubic spline) Csound generators. All this is set up in a "-cs" Csound instrument file such as the one shown below, and documented in chapter 17 of the BP2.9.8 reference manual.

Csound instrument file
  • Open "-cs.tryCsound" in the CSOUND resources folder. This page is in autosave mode (see below): changes to Csound instruments are saved automatically twice per minute.
  • This file is linked to a Csound orchestra file called "tryCsound.orc". As this file is missing from the "csound_resources" folder, a link is displayed to create it. Otherwise, the link would open it for editing. The arguments declared in the orchestra must match those in the instrument file.
  • The Tables text area contains Csound function tables. They are not used to create the score. They are only copied at the beginning of it.
  • Csound instruments can be associated with MIDI channels. For example, here, MIDI messages sent to channel 2 are converted into notes of instrument 3 "Harpsichord".
  • At the bottom of the page is the list of Csound instruments declared in this file. They can be deleted, restored and duplicated in the same way as sound-object prototypes. Clicking the blue button with the name of an instrument opens its editor.

A simple orchestra file called "0-default.orc" is provided in the "csound_resources" folder. It is used when no other orchestra is specified, as in our first examples. See also the Simple Csound orchestra page.

Editing a Csound instrument

Page of a Csound instrument
Page of a Csound instrument showing the parameters associated with MIDI controllers

The Csound instrument editor is very similar to the one of BP2.9.8. A detailed description can be found in chapter 17 of the BP2.9.8 reference manual.

  • For example, let us look at the instrument Harpsichord in "-cs.tryCsound". Its index is "3", which means that it can be called as _ins(3) or _ins(Harpsichord) in a Bol Processor score.
  • The parameters displayed on the "Harpsichord" page are those associated with MIDI controllers. They can change continuously if two arguments are given for their values at the start and at the end of each note. The argument under "table" is the reference of an optional function table.
  • For the volume parameter, the MIDI values "0", "64" and "127" are converted to the Csound values "-24", "0" and "+24" respectively. This converts a linear scale into a logarithmic scale.
  • The start and end values of a continuously changing volume are sent to arguments "7" and "8" respectively. The orchestra uses them to set the volume, with the GEN07 (linear interpolation) or GEN08 (cubic spline) generators.
  • Given three pairs of input/output values, the Bol Processor tries to define a quadratic mapping between input and output. It is not always possible to fit the three values to a monotonic quadratic function… See the Csound argument mapping page for a detailed explanation.
  • At the bottom of the page is a list of Csound parameters that have nothing to do with MIDI controllers. This is where Csound production by the Bol Processor can differ radically from MIDI!
  • This instrument has a single additional parameter called "blurb".
The blurb parameter
A specific "blurb" Csound parameter

These additional parameters can be created, deleted and restored in the same way as instruments. The interface makes sure that a new parameter does not have the same name as an existing or (temporarily) deleted parameter.

Let us look at the "blurb" parameter (image on the left). Each parameter has a default value, which is not necessarily zero. Values found in Csound scores can be combined additively (ADDval) or multiplicatively (MULTval). The "blurb" parameter sends its start value to argument "9" of the Csound score, and its end value (for continuous variations) to argument "10".

Using a Csound instrument in a grammar

Csound logo

Here is a simple example showing the basic features of Csound in the Bol Processor. A complete demonstration on a real musical example can be found on the Sarasvati vina page. All the features of the Csound implementation are documented on the Csound checkup and Csound objects pages, with examples that you can try yourself.

The Data project "-da.tryCsound" calls "-cs.tryCsound" and uses its instrument "Harpsichord" (number 3). Type the following line in a Data project linked to "-cs.tryCsound" and play it with the Csound score output:

_ins(Harpsichord) _volumecont _volume(127) A4 G4 C5 A5 A4 G4 C5 A5 _volume(0)

The Csound score produced is:

; Csound score
f1 0 256 10 1
f2 0 256 10 1 0.5 0.3 0.4

t 0.000 60
i3 0.000 1.000 440.000 8192.000 8192.000 127.000 111.125 0.000 0.000 0.000 0.000 0.000 ; A4
i3 1.000 1.000 391.995 8192.000 8192.000 111.125 95.250 0.000 0.000 0.000 0.000 0.000 ; G4
i3 2.000 1.000 523.251 8192.000 8192.000 95.250 79.375 0.000 0.000 0.000 0.000 0.000 ; C5
i3 3.000 1.000 880.000 8192.000 8192.000 79.375 63.500 0.000 0.000 0.000 0.000 0.000 ; A5
i3 4.000 1.000 440.000 8192.000 8192.000 63.500 47.625 0.000 0.000 0.000 0.000 0.000 ; A4
i3 5.000 1.000 391.995 8192.000 8192.000 47.625 31.750 0.000 0.000 0.000 0.000 0.000 ; G4
i3 6.000 1.000 523.251 8192.000 8192.000 31.750 15.875 0.000 0.000 0.000 0.000 0.000 ; C5
i3 7.000 1.000 880.000 8192.000 8192.000 15.875 0.000 0.000 0.000 0.000 0.000 0.000 ; A5
;
e 10.000
Volume mapping of Csound instrument 3
Mapping of volume in Csound instrument 3
  • Argument "4" is the pitch, here in Hertz (440 for A4).
  • Arguments "5" and "6" are the start and end values of the pitchbend, as specified by the instrument. They remain at the default value "8192" in the absence of pitchbend instructions.
  • Arguments "7" and "8" are the start and end values of the volume. The volume decreases from 127 to 0 over the eight notes, as expected.
  • The _volumecont instruction at the beginning of the sequence means "continuous volume". It resolves a difference between MIDI and Csound: in MIDI, each event happens at a point in time, whereas a Csound note is a segment of time with a duration. It is then up to the orchestra to decide how the parameter changes from the start to the end of each note.
  • Arguments "9" and "10" remain at the default value "0" of the unused modulation parameter.
  • Arguments "11", "12" and "13" remain at the default value "0" of the unused panoramic parameter.

Csound scores created with "-cs.tryCsound" cannot be played with "0-default.orc", because their arguments do not match.

A real musical example using many features of Csound in the Bol Processor is a phrase of Carnatic music designed by Srikumar K. Subramanian in 1996. Read the description of this example and listen to it (in just intonation):

"Pallavi" of the song "Maayaatiita Svaruupini, Nannu brovave" in raga "mayamaalavagaula"

Editing the Timebase

A timebase with 3 tracks
A timebase with 3 tracks set up in 4 beats

The Timebase is a tool for creating a rhythmic pattern (a "tick pattern") to be superimposed on a piece of music produced by the Bol Processor. Superimposition in real time has not yet been implemented in the 'BP3' console, but you can try it by importing a production of the Bol Processor saved as a MIDI file.

  • Create a new timebase called "try.bptb" in the "ctests" folder and open it.
  • By default, the timebase contains 3 tracks, 2 of which are set to a simple 4-beat pattern at mm = 60 beats/minute. The third track is empty. Fill it with 4 strokes on key = 100 at a speed ratio of 2/1.
  • Now listen to the combined tracks (repeated 3 times):
  • To understand the structure, you can mute some tracks.
  • Now click "Choose File" to select a MIDI file, for example "acceleration.mid", and click the "send" button to import it.
A MIDI file loaded in the timebase
A MIDI file "acceleration.mid" has been loaded in the timebase.
  • You can listen to the imported file alone, and to its combination with the tick pattern:
A change of tempo suggested after loading a MIDI file
After loading "this_song.mid", a change of tempo is suggested.
  • The two fit together because the piece was created at mm = 60 and in a rhythmic pattern of 4 beats. Try changing the metronome value in the table above. You will get a warning if the metronome setting does not match the tempo declared in the imported MIDI file.
  • For example, try a rhythmic cycle above "this_song.mid" in the "ctests" folder. You will be asked to set the metronome to 9 beats in 4 seconds, as declared in the MIDI file (picture on the right). The timing is perfect:
  • You can add as many tracks as you like. (The limit in BP2 was 3 tracks.)
  • Playing with speed ratios creates complex cycles that can be used to control a drum machine, if the appropriate channels, key numbers and velocities are set up. Traditional rhythmic structures can also be programmed easily. See the examples below:
Panchamasvari tala

Tick patterns as polymetric expressions

➡ For experts!

The Timebase page offers a convenient way of superimposing a tick pattern on a production of the Bol Processor saved as a MIDI file. Timebases can also control a MIDI drum machine taking part in the performance. It would be better to make the drum track part of the performance itself, since polymetric expressions can handle superimpositions. We will see that this is often possible, but tedious. (A more systematic approach is described on the Timebase to polymetric page.)

A polymetric equivalent of the tick pattern shown above would be:

{_chan(1) _vel(120) _staccato(99) C8 - - -, _chan(1) _vel(120) _staccato(99) - C7 C7 C7,
_chan(1) _vel(120) _staccato(98) E7 E7 E7 E7 E7 E7 E7 E7}

This expression is displayed at the bottom of the Timebase page.

Let us try to add this polymetric expression as a variable "Drum" to the grammar "-gr.acceleration":

S --> {Piano, Drum}
Piano --> _vel(60) A B _vel(65) C D _vel(70) E F _vel(75) G _vel(77) H _vel(80) I _vel(85) J _vel(87) K _vel(90) L
A --> E2 .
B --> D2 A
C --> B2 B
D --> G2 C
E --> F#2 D
F --> A#2 E
G --> C2 F
H --> G#2 G
I --> A2 H
J --> D#2 I
K --> C#2 J
L --> F2 K
Drum --> {_chan(1) _vel(120) _staccato(99) C8 - - -, _chan(1) _vel(120) _staccato(99) - C7 C7 C7,
_chan(1) _vel(120) _staccato(98) E7 E7 E7 E7 E7 E7 E7 E7}

Unfortunately, this does not work, because the "Drum" pattern should be repeated at the right tempo instead of being stretched to the duration of "Piano"… The solution is to replace it with a cyclic sound-object. Let us do it:

  • Create the following "-gr.drum" grammar and use it to produce a MIDI file called "drum.mid":
    S --> {_chan(1) _vel(120) _staccato(99) C8 - - -, _chan(1) _vel(120) _staccato(99) - C7 C7 C7,
    _chan(1) _vel(120) _staccato(98) E7 E7 E7 E7 E7 E7 E7 E7}

  • Create a sound-object prototype file called "-so.drum" and define a sound-object called "cycle2".
Setting a sound-object to cyclic
Setting a sound-object to "cyclic"
  • Set it to "cyclic" (see picture on the left).
  • Import "drum.mid" into the sound-object prototype "cycle2".
  • Bad news: its duration is 6000 ms instead of the expected 4000 ms…
  • A look at EXPLICIT MIDI codes shows that the last 2 seconds are a fade-out added by the Bol Processor to avoid an abrupt end.
  • Good news: the sound-object prototype editor lets you crop the sound-object by cutting its end. So let us crop it to 4000 ms.
  • Listen to the cropped "cycle2" sound-object and look at its image. Everything is perfect. This object sounds identical to the pattern programmed on the Timebase page:

    Cropping is done carefully: if necessary, the algorithm rewrites the "NoteOff" messages deleted by the cropping.
  • Now the sound-object can be added to the grammar as follows:
    -al.drum
    S --> {Piano, cycle2}
    Piano --> _vel(60) A B _vel(65) C D _vel(70) E F _vel(75) G _vel(77) H _vel(80) I _vel(85) J _vel(87) K _vel(90) L
    A --> E2 .
    B --> D2 A
    C --> B2 B
    etc…
    J --> D#2 I
    K --> C#2 J
    L --> F2 K

The cropped cycle2 sound-object prototype
The cropped “cycle2” sound-object prototype
  • The "cycle2" sound-object and its prototype file "-so.drum" must be declared in the following "-al.drum" alphabet file:
    -so.drum
    *
    cycle2

    The ‘*’ on the second line of the alphabet is an arbitrary symbol declaring a homomorphism — not used here.

  • This method follows the Bol Processor model, but it is tedious. Worse still, the equivalent polymetric expression can become extremely complex if the speed ratios and/or beat cycles of the tracks are not the same. In this case, it is not displayed at the bottom of the Timebase page.

Scripts

  • Bol Processor BP2.9.8 was fully scriptable: all commands launched from its menus could be recorded as sequences of script instructions and run again at will. This included opening folders and files, modifying text or doing something with the selection.
  • A script was run every evening for about half an hour, checking all procedures and tracking changes in the output data, in addition to the sound check.
  • This level of automation is not possible in BP3, because the console and its PHP interface are separate. As a result, many BP2 script instructions are not valid in BP3. They are ignored when the script is run.
  • Consider for instance "-sc.tryMe":
    Show messages OFF
    Note convention = English
    Show graphics ON
    Play - - {2,G4,E4,C4,- C5 - C5 {C5_-,A#4_ _}}
    Show messages ON
    Activate window Scrap
    Type Welcome to <a href="https://bolprocessor.org/">Bol Processor BP3</a>...
    Type Hope you <big><i><font color="green">enjoyed</font></i></big> the music!
    Type BP3 is now waiting for you to play ‘C4’ on the MIDI keyboard
    Type <return>
    Wait for C4 channel 1
    Run script -sc.trySubscript
    Type That's all folks!

Executing the -sc.tryMe script
Executing the "-sc.tryMe" script. A musical sequence is played on MIDI and a Csound score is created.
  • In this script, the instructions "Show messages OFF", "Show graphics ON", "Show messages ON", "Activate window Scrap" and "Wait for C4 channel 1" are ignored. The "Play" instruction expands the polymetric expression - - {2,G4,E4,C4,- C5 - C5 {C5_-,A#4_ _}} and sends it to MIDI in real time. The note convention is set to "English" to recognise "G4", "E4" etc. as simple notes. The tempo is the standard metronome = 60 beats per minute.
  • The "Type" instruction displays a line of text (which may contain HTML elements).
  • This script calls a subscript called "-sc.trySubscript" in the same folder. Its content is:
    Load project -gr.Ames
    Csound score ON
    Produce items

  • Here the machine calls the grammar "-gr.Ames" and sets the output format to "Csound score".
  • The execution of the script is displayed in a pop-up window (see image above), which lists (in red) the commands sent to the console. The second command produces a Csound score, as expected.
  • The image also shows (light blue) buttons for entering script instructions, so that no typing is required. A CHECK THIS SCRIPT button shows any errors, such as a file not found.
  • Below the script, the LIST ALL SCRIPT INSTRUCTIONS button lists all the instructions handled by BP2.9.8, indicating which ones are obsolete in BP3 and which ones are under development.

Autosave

The autosave feature works like the automatic saving of Google Docs or WordPress pages. It is used when editing sound-object prototypes and Csound instruments.

When you edit the prototypes of "-so.abc1", all data belongs to this file. Clicking the SAVE THIS PROTOTYPE button while working on a particular prototype only updates a temporary file, whose path is shown at the top of the page. When you have finished, you are expected to return to the "-so.abc1" page and click the SAVE ‘-so.abc1’ INCLUDING ALL CHANGES TO PROTOTYPES button. Fortunately, the autosave, shown by a red line at the top of the page, does it for you in the background.

The same feature is used on the page of Csound instrument files. For instance, the file "-cs.tryCsound" is saved automatically every 30 seconds while you are editing its instruments or additional parameters.

👉 Temporary files are kept in the "temp_bolprocessor" folder, in a subfolder whose name contains the identifier of your browser session. If you restart your browser or your computer, a new session begins and a new subfolder is created. The interface deletes subfolders that are more than 24 hours old. Thanks to the autosave, no data is lost.

For developers: the autosave is a simple call of JavaScript code in the files "autosaveObjects.js" or "autosaveInstruments.js". The command is myVar = setInterval(savePost, 30000), where "30000" means 30 seconds. A savePost() function sends POST requests to "autosaveObjects.php" or "autosaveInstruments.php".

Where to go next

You have now seen the main features of the Bol Processor. Here are some suggestions for the next steps:

👉 Don't hesitate to ask questions or send suggestions via the contact form, or join the BP developers list on SourceForge.

Code explained

This section is for software specialists interested in a in-depth analysis of the implementation of algorithms, all created by Claude Opus 5.5…

Code explained

No posts found.

Time-setting an item: how TimeSet() works

This page is for programmers who want to read, maintain or extend the code that computes the physical dates of sound-objects, notes and time patterns once an item has been produced. This is done by TimeSet() and SetTimeObjects(), in the console's source file TimeSet.c. The page describes their algorithm step by step.

The theory behind this code is explained in the paper Time-setting of sound-objects: a constraint-satisfaction approach (Bel 1992). This page uses its vocabulary: phase diagram, structure of time, time streaks, pivot, local drift, global drift, correction 1 and correction 2. References such as “paper §5.2” point at its sections. Where the code has gone further than the paper, or differs from it, this page says so.

The code lives in four C files of the console (source/BP3/):

  • TimeSet.c contains TimeSet(), SetTimeObjects() and GetCap();
  • FillPhaseDiagram.c contains FillPhaseDiagram(), MakeEmptyTokensSilent() and Class(), which build the phase diagram;
  • SetObjectFeatures.c contains Calculate_alpha(), FixDilationRatioInCyclicObject(), SetLimits() and FixObjectTimings(), which compute the dilation ratios, the limits of each object and its default dates;
  • TimeSetFunctions.c contains Locate(), the constraint solver, and its subroutines Situation_ok(), Possible_choices(), Next_choice(), Alternate_correction1() and Solution_is_accepted().

Comments of the form // note 12 have been placed in TimeSet.c. Each one points to the numbered note of this page that explains the code below it. Searching for // note 12 finds every place that note 12 describes. Line numbers are not given because they change with every revision.

Where TimeSet() stands in the production of music

A grammar produces an item: a string of terminal symbols, notes, performance controls and polymetric structures such as {C4 D4 E4, F3 G3}. Playing this item takes three steps, called from PlayBuffer1() in PlayThings.c:

  1. PolyMake() (Polymetric.c) normalises the polymetric structure. It computes Ratio, the number of grid units per beat that represents every duration of the item exactly, and Kpress, a compression rate used when the grid would be too large (note 8).
  2. TimeSet() places every object on the phase diagram (FillPhaseDiagram()), then computes the date at which each one starts and ends (SetTimeObjects()). Constraints such as overlapping, continuity, truncation, relocation and tempo breaks are resolved here.
  3. MakeSound() (MakeSound.c) reads the timed objects and sends their events to the outputs. Its algorithm is described on the page Playing an item: how MakeSound() works.

PlayBuffer1() interprets the result of TimeSet(): OK lets MakeSound() play the item, MISSED displays error 37 (no solution could be found, note 17), ABORT and EXIT stop, and AGAIN is noted in the variable again, although none of the functions called by TimeSet() returns it at present.

The data used by SetTimeObjects()

The phase diagram

The phase diagram (paper §1 and §3) is the table p_Seq. Each line nseq, from 0 to *p_nmax, is a sequence: a voice of the polymetric structure. Each column i, from 0 to maxseq, is a position in symbolic time. The cell (*((*p_Seq)[nseq]))[i] contains an instance index k:

  • k ≥ 2: an instance (*p_Instance)[k] that starts in this column;
  • k = 1: a silence -;
  • k = 0: an empty cell. The object or silence before it continues. This is the prolongation _ of the paper (its null object E0);
  • k = -1: the end of the sequence, called NIL in the paper (its virtual object E-1). (*p_imaxseq)[nseq] is its column.

The paper numbers columns from 1, and gives all real objects an index k ≥ 1. The code numbers columns from 0, reserves k = 0 and k = 1 for _ and -, and gives real instances k ≥ 2. The scans of a sequence rely on finding the -1 marker. The idiom inext = i; while(seq[++inext] == 0);, found in every function below, finds the next column that is not empty, i.e. the end of the object starting in column i.

The instances

Each instance (*p_Instance)[k] has a field object, called j in the code, which tells what it is: a sound-object if 1 < j < Jbol, a time pattern if Jbol ≤ j < 16384, a simple note of key j - 16384 if j ≥ 16384, and an out-time object (written <<…>>, with no duration) if j < 0. SetTimeObjects() computes the following fields:

  • alpha: the dilation ratio, the α(k) of the paper. It is the ratio between the duration of the instance and that of its prototype. If α > 1 the object is played slower than its prototype.
  • beta and ncycles: the ratio applied to the dates of the events, and the number of repetitions of the periodical part of a cyclic object (note 12).
  • starttime and endtime: the dates in milliseconds, the t1(k) and t2(k) of the paper.
  • truncbeg and truncend: the durations cut at the beginning and at the end, TrBeg(k) and TrEnd(k).

The prototypes

The properties of a sound-object prototype j come from the -so file. They are global tables indexed on j. Those used here are:

  • p_Dur: the duration of the prototype in milliseconds, and p_Tref: the reference period. A prototype with Tref > 0 is striated: its duration is defined relative to a beat. A simple note is treated as an object of 1000 ms.
  • p_PivMode, p_PivPos: the pivot, the time point placed on the streak (paper §2).
  • p_PreRoll, p_PostRoll: durations played before the start or after the end.
  • p_OkExpand, p_OkCompress, p_FixScale, p_RescaleMode, p_AlphaMin, p_AlphaMax, p_CyclicMode: what dilation ratios are allowed (note 12).
  • p_OkRelocate, or else p_MaxDelay and p_MaxForward: whether the object can be moved (Reloc in the paper), and by how much.
  • p_CoverBeg, p_CoverEnd, p_MaxCoverBeg, p_MaxCoverEnd: whether its beginning or end may be overlapped by other objects of the same sequence (OverBeg and OverEnd), and by how much.
  • p_ContBeg, p_ContEnd, p_MaxBegGap, p_MaxEndGap: whether its beginning or end must join a neighbour (ContBeg and ContEnd), and the largest gap allowed.
  • p_TruncBeg, p_TruncEnd, p_MaxTruncBeg, p_MaxTruncEnd: whether its beginning or end may be truncated, and by how much.
  • p_BreakTempo: whether a global drift may start after it (BrkTempo).

In the paper, these properties are TRUE or FALSE. In BP3, most of them come with a limit, whose mode (…Mode tables) is FIXVALUE (in milliseconds), PERCENT (a percentage of the duration of the instance) or IRRELEVANT (no limit). SetLimits() converts them to milliseconds (note 13).

Striated and smooth time

The setting Nature_of_time is STRIATED or SMOOTH (paper §7.2):

  • In striated time, the structure of time is given in advance by the metronome. Column i has a date (*p_T)[i], its time streak, and each object is placed with its pivot on the streak of its column. The constraint solver may then move objects, truncate them, or delay all following streaks (a global drift, or tempo break).
  • In smooth time, there is no structure of time in advance. The objects of the first line are played one after the other, each one with the duration of its prototype. Their dates become the streaks, and the objects of the other lines are fitted between them.

Both modes use the same functions, with branches on nature_time. It is copied from Nature_of_time at the start because it must not change during the computation.

Overview of the algorithm

TimeSet() prepares the tables, calls FillPhaseDiagram(), then SetTimeObjects(), and reports the ties that could not be resolved (notes 1–6).

SetTimeObjects() works as follows:

  1. It computes the default structure of time: the dates (*p_T)[i] of all columns, from the metronome in striated time, or zero in smooth time (notes 7–10).
  2. It processes the sequences in order, from line 0 to line *p_nmax (note 11). For each sequence: 
    1. it computes the dilation ratio of every object (note 12) and its limits of overlapping, gap and truncation (note 13), once only;
    2. it computes the default dates of every object, with its pivot on its streak (note 15);
    3. it calls Locate(), which scans the sequence from left to right and changes these dates until all constraints are satisfied (note 16);
    4. if Locate() fails, it releases the constraints step by step and tries again (note 17);
    5. it adds the global drift found by Locate() to the structure of time (notes 19–20). In striated time, a global drift means that the sequences already placed may no longer be correct, so the whole loop starts again from line 0, as the paper explains at the end of §2;
    6. it updates the limits tmin and tmax of the item, tmax being the latest end of all its objects (note 21).
  3. Finally, it applies legato and staccato to all objects, and moves tmax to the end of a legato object that ends later (notes 22–24).

Step 1 — TimeSet()

Note 1 — Starting

The function returns ABORT if an emergency stop was requested. *p_tmin and *p_tmax, the limits of the item in time, start at Infpos and Infneg so that the first object found replaces them (note 21).

Chunk_number counts the calls when the item is played in chunks (PlayChunks). It is only used in messages. It is not increased when improvising.

p_Articul is allocated with one value per instance (MaxObjects). FillPhaseDiagram() stores in it the articulation of each instance, i.e. the value of _legato() or _staccato() in force, as a percentage. It is used at the end (note 23) and freed when TimeSet() returns.

Note 2 — Tie tables

Ties (C4& … &C4, and the same for sound-objects) are resolved by FillPhaseDiagram(), which needs four tables allocated here:

  • p_Tie_note[channel][key] counts the ties opened and not yet closed for each MIDI channel and key (128 keys). Since 2026-11-13 it is a counter, not a flag, so that several ties of the same note can be open at the same time;
  • p_Tie_event[instrument][j] does the same for sound-objects, for each Csound instrument and each prototype j. Its size, maxties = Jbol + Jpatt, covers sound-objects and time patterns;
  • p_Missed_tie_note and p_Missed_tie_event count the ties that could not be closed. They are reported at the end (note 6).

Note 3 — Making empty objects silent

MakeEmptyTokensSilent() (FillPhaseDiagram.c) scans the item before the phase diagram is built:

  • A variable left in the item (token T4, when the grammar did not rewrite it) becomes a new silent sound-object with the same name (token T47). This creates a new prototype, so Jbol increases, and a new instance, so MaxObjects increases and p_Instance, p_ObjectSpecs and p_Articul are enlarged. Its duration is 1000 ms.
  • A sound-object with no MIDI codes and no Csound score becomes a silent object. If it is striated, its duration is its reference period Tref; otherwise it is 1000 ms.

Silent objects still take their place in the phase diagram and in the constraints. Because new prototypes may have been created, the tie tables of note 2 are enlarged to the new value of Jbol + Jpatt (fixed on 2026-11-06).

Note 4 — Filling the phase diagram

FillPhaseDiagram() reads the item, creates an instance for each sound-object, note and time pattern, with the values of the performance controls in force (channel, velocity, articulation, transposition, continuous parameters…), and places it on the phase diagram. It returns the number of instances (*p_kmx), the number of columns (*p_maxseq), the index of the last line (*p_nmax) and the last column of each line (p_imaxseq). It also adds an out-time silence at the end of the item, carrying the last values of the performance parameters.

It computes CorrectionFactor, the ratio between the expected duration of the item and the duration given by the phase diagram. It differs from 1 when Prod and Ratio overflowed in PolyMake(). The message Possible error of duration is displayed when it is outside 0.9–1.1.

Note 5 — Measuring time

The time spent in the production, in FillPhaseDiagram() and in SetTimeObjects() is added to ProductionTime, PhaseDiagramTime and TimeSettingTime. The console displays them at the end of the run (Phase-diagram filling time, Time-setting time) when they are not zero. They are measured with time(), so in whole seconds.

Note 6 — Missed ties and cleaning up

After time-setting, or after an error, every note and sound-object with ties that could not be closed is reported, with the number of occurrences and the channel or Csound instrument, followed by the total number of notes or events concerned. These are warnings (messages starting with =>): the item is still played. Then the tie tables and p_Articul are freed, and the result of SetTimeObjects() is returned.

Step 2 — The structure of time

Note 7 — Enlarging the sequences

Each line of p_Seq is enlarged to maxseq + 50 cells. The working tables (note 10) have the same size. The margin is needed because some scans read a few cells past the end marker of a line. Locate() allocates its own tables with 20 extra cells for the same reason.

Note 8 — Time streaks

In striated time, the date of each column is computed from the metronome:

  • period = Pclock × 1000 × CorrectionFactor / Qclock is the duration of a beat in milliseconds. The metronome is Qclock / Pclock beats per second.
  • A beat contains Ratio grid units. When the item would need too many columns, PolyMake() chose a compression rate Kpress: one column of the phase diagram then holds Kpress grid units. This is the quantization of paper §7.1.
  • The loop moves a position in along the grid, in steps of Kpress units. Class(in) gives the column of this position. The first time a column is reached, its date is period × (in - 1) / Ratio.
  • When Kpress > 2, the dates of the neighbouring columns are set to the same value. Because of rounding, a column could otherwise be skipped and keep the date 0. Calculate_alpha() reports this case as a Probable rounding error.

In smooth time, all dates are set to zero: they will be computed from the objects of the first line (note 20).

Note 9 — Displaying the phase diagram

This block is only compiled if DISPLAY_PHASE_DIAGRAM is set to 1 at the top of TimeSet.c. It prints the list of instances, then the phase diagram itself if it has fewer than 1000 objects, then checks that every instance points at a valid object. It is a debugging aid, and it prints its results even when trace_timeset is 0.

Note 10 — Working tables

Tables with one value per column (size maxseq + 50):

  • p_DELTA: the global drift of each streak computed by Locate(), the Δ(i) of the paper (notes 19–20);
  • p_marked: in smooth time, TRUE for columns whose date is known (note 20);
  • p_time1, p_time2: the default start and end dates of the object starting in each column (note 15);
  • p_maxcoverbeg, p_maxcoverend, p_maxgapbeg, p_maxgapend, p_maxtruncbeg, p_maxtruncend: the limits of the object starting in each column (note 13).

p_alphadone has one value per line: TRUE once its dilation ratios and limits are computed (note 11).

max_end_time is the date of the last column. It is used in note 24.

Step 3 — Placing the sequences

Note 11 — The loop on sequences

The sequences are processed in order, from line 0. The label STARTAGAIN marks the start of this loop: after a global drift in striated time, the program comes back here and processes all lines again with the new structure of time (note 19). The dilation ratios and limits of a line are computed only once, during the first pass (p_alphadone). During the next passes, the objects keep their durations and only their dates change: this is the meaning of a tempo break, which adds time between objects rather than stretching them.

The order of the lines matters in smooth time: the dilation ratios of line nseq depend on the dates found for the lines before it (note 12).

With trace_timeset, a message gives the number of objects, the compression rate and the line being processed.

Note 12 — Dilation ratios: Calculate_alpha()

Calculate_alpha() (SetObjectFeatures.c) computes alpha for every object of the line. As the paper says (§3), all ratios are computed before the constraints are solved. The symbolic duration of an object, in beats, is d = (inext - i) × Kpress / Ratio, where inext is the next column that is not empty.

Striated time, or the first line in smooth time. The ratio is the duration available for the object, divided by the duration of reference of its prototype:

  • in striated time, the available duration is T[inext] - T[i]; the reference is 1000 ms for a simple note, Tref for a striated object (or a silent one), and Dur for a smooth object. Time patterns get α = 0 in striated time, because they carry no events;
  • in smooth time with a metronome (Pclock > 0), the available duration is d beats at the metronome period; without a metronome, alpha = d.

Other lines in smooth time. The dates of the first line are known only on its marked columns (note 20). Between two marked columns iprev and inextm, the duration To = T[inextm] - T[iprev] is shared among the objects of the line in proportion to r × d, where r = Dur / Tref for a striated object and 1 otherwise. The sum of r × d is sigmaridi, so alpha = To × r × d / dur / sigmaridi. The last object of a section gets exactly the remaining time, which compensates the rounding errors. A silence that starts and ends in the same section gets a date, and its column is marked, so that the next lines can use it. Beyond the end of a short line, the cells are treated as silences up to the end of the phase diagram, if more lines follow.

Limits. The ratio found is then restricted by the properties of the prototype:

  • time patterns keep it;
  • with RescaleMode == OK_RESCALE, the ratio is accepted, within the limits below;
  • a prototype with fixed scale (FixScale) that is not cyclic gets α = 1;
  • a cyclic object (one with a periodical part) that must be expanded is handled by FixDilationRatioInCyclicObject(). It computes ncycles, the number of times the periodical part is repeated, and beta, the ratio applied to the dates of its events. If the object cannot be stretched, beta = 1 and the periodical part is repeated as many times as needed (rounded to an integer if ForceIntegerCycles). Otherwise, it is stretched, up to AlphaMax, and repeated. alpha is then recomputed from the actual duration;
  • with RescaleMode == DILATION_RATIO, the ratio is kept between AlphaMin and AlphaMax;
  • otherwise, a ratio above 1 is only accepted if OkExpand, and a ratio below 1 only if OkCompress. Otherwise α = 1.

If ForceRatio is not negative, it replaces alpha and beta. For an object that is not cyclic, beta is not final: it is set equal to alpha after articulation (note 23) and again by MakeSound().

Note 13 — Limits: SetLimits()

SetLimits() (SetObjectFeatures.c) converts the properties listed in “The prototypes” above into milliseconds for the object starting in each column, from its duration dur = beta × Dur (1000 ms for a note, 0 for an out-time object):

  • maxcoverbeg, maxcoverend: how much of its beginning or end may be overlapped. Zero if the property is not set, Infpos if there is no limit. If both together cover the whole object, both become Infpos.
  • maxgapbeg, maxgapend: the largest gap allowed before or after it. Infpos if continuity is not required.
  • maxtruncbeg, maxtruncend: how much may be truncated. Zero if truncation is not allowed, and never more than dur.

Simple notes and silences have no limit of overlapping, no continuity requirement, and may be truncated entirely.

Note 14 — Relaxing constraints

Two tables, with one value per column, release part of the constraints for the object starting in that column:

  • p_coverok[i]: any overlapping between this object and the preceding one(s) is accepted;
  • p_discontinuityok[i]: any gap between them is accepted.

They are set to FALSE at the start of each line, and set to TRUE by note 17 when no solution is found. The setting Ignore constraints in time setting (NoConstraint) sets them all to TRUE from the start. SetConstraintRelease(), at the end of TimeSet.c, sets a whole table.

Until 2026-11-14, these were two global flags, CoverOK and DiscontinuityOK, which applied to the whole line: a single object that could not be placed released the constraints of all objects of its line. Other objects could then overlap their neighbours, although they could have been placed correctly.

Note 15 — Default dates: FixObjectTimings()

FixObjectTimings() (SetObjectFeatures.c) computes the default position of each object, “with its pivot located exactly on its reference streak” (paper §5). For the object starting in column i:

  • Sound-object: t1 = T[i] - pivot, where the pivot is alpha × Dur × PivPos / 100 in mode PERCENT, or PivPos milliseconds otherwise. A random shift may then be added (_rndtime(), RandomTime()). With PlayFromInsertionPoint, t1 = T[i]. Then t2 = t1 + alpha × Dur. A negative pre-roll moves t1 earlier and a positive post-roll moves t2 later.
  • Time pattern: t1 = T[i], t2 = t1 + alpha × Dur.
  • Simple note: t1 = T[i], possibly with a random shift, t2 = t1 + alpha × 1000. The pivot of a note is its beginning.
  • Silence: t2 = t1 = T[i], except on the first line in smooth time, where a silence has a duration alpha × Dur.
  • Out-time object or empty cell: t1 = t2 = T[i].

These dates go into p_time1[i] and p_time2[i]. They are recomputed each time a line is tried again (label TRY), because T may have changed. With trace_fix, T and time2 are printed before and after.

Note 16 — The constraint solver: Locate()

Locate() (TimeSetFunctions.c) implements the flowchart of paper §5.1 (Fig.5). It scans the sequence from left to right and changes the dates of objects until all constraints are satisfied. The code follows the flowchart closely, with goto labels named after its boxes: START, INCREMENT, CHECK, NEWCHOICE1, NEWCHOICE2, DECREMENT.

Dates. For the object in column i:

  • tp1[i], tp2[i]: its proposed dates, and ts1[i], ts2[i]: its dates in the solution being built. They start at time1 and time2 plus ddelta0[i].
  • Ts[i]: the largest end date of the objects before column i, as in paper §5.2 (Fig.6). BreakTempoPrev[i] tells whether the object that defines Ts[i] allows a tempo break.
  • tscover[i]: the earliest start allowed by the overlapping limits of the objects before it (their end minus maxcoverend).
  • tsgap[i]: the latest start allowed by the continuity limit of the object before it (its end plus maxgapend).
  • delta1[i], delta2[i]: the local drift δ(k) of the object, from correction 1 and correction 2.
  • ddelta1[i], ddelta2[i]: the global drift started in this column, and ddelta0[i]: the global drift accumulated from the columns before (in striated time only).

Situations. The scan starts at i0, the first column that is not a silence. For each object, shift1 = Ts[i] - tp1[i] (paper §5.2):

  • shift1 < 0: there is a gap after the previous object (situation 1). The trace says the object “should save” this time.
  • shift1 = 0: it starts exactly when the previous one ends (situation 2). Always acceptable.
  • shift1 > 0: it overlaps the previous object (situations 3 and 4). The trace says it “should spend” this time.

Situation_ok() decides whether the situation is acceptable. In BP3 it uses the limits of note 13 rather than the yes/no conditions of the paper's Fig.7:

  • a gap is accepted if continuity is released for this object (p_discontinuityok[i], note 14), or for a simple note, or if the object starts before tsgap and the gap does not exceed its maxgapbeg;
  • an overlap is accepted if overlapping is released for this object (p_coverok[i]), or if the object starts after tscover and the overlap does not exceed its maxcoverbeg;
  • the first object of the line is always accepted, and so is a silence in striated time;
  • on the first line in smooth time nothing is accepted: every object is moved to the end of the previous one, which is how the first line defines the dates (note 20). On the other lines in smooth time, an overlap is not accepted for an object whose column has no known date, or for a note or a silence.

When the situation is not acceptable, its column and its shift are stored in *p_iconflict and *p_shiftconflict. If Locate() fails, they tell which object could not be placed, and whether it overlapped or was separated from what precedes it (note 17).

An accepted situation leads to INCREMENT: Ts, tscover and tsgap are updated for the next object, and the scan moves on.

Correction 1 (paper §5.3) changes the start of the current object by shift1. Possible_choices() builds the set of solutions sol_set1[i], in this order:

  1. Shift the object (local drift): if it is relocatable, or if the shift does not exceed MaxDelay (to the right) or MaxForward (to the left). Notes can always be shifted. An object is never shifted before date 0.
  2. Break tempo (global drift): only to delay (shift1 > 0), if the object that defines Ts allows it (BreakTempoPrev), or always in smooth time. On the first line in smooth time, it is the only solution offered.
  3. Truncate the beginning: only to delay, if the overlap does not exceed maxtruncbeg.
  4. (Truncate the end, for correction 2 only.)
  5. Revise the previous objects: always possible after the first object.

Next_choice() takes the first solution of the set and removes it from the set. Solution 0 moves both dates (delta1), solution 1 also moves the streak and all those after it (ddelta1), solution 2 moves only the start date and sets truncbeg. The scan then continues to the next object (INCREMENT).

Correction 2. If the set contains only “revise”, or if “revise” is chosen, the program goes back (DECREMENT) to the previous object and tries to change its end by shift2 = -shift1. Objects whose end does not define Ts are skipped: they are “not the one concerned”. A new set sol_set2 is built for this object: shift it, truncate its end (if -shift2 does not exceed maxtruncend), or revise the objects before it. Revising goes further back only if the object can move by that amount, or if an earlier column allows a tempo break (ibreak); otherwise Locate() gives up.

Alternate correction 1 (paper §5.4). When correction 2 has moved the start of a previous object, its situation with its own predecessor may have become wrong. Alternate_correction1() checks it, taking into account the constraints released for this object. If it overlaps too much, it first tries to truncate its beginning. If the situation is acceptable, it returns 0 and the scan continues forward from this object, re-examining all objects after it. Otherwise it returns the remaining shift: another solution of sol_set2 is tried, or the program goes back one more object.

End of the sequence. When the scan reaches the end marker, Solution_is_accepted() is called. It prints the solution if Time setting display (DisplayTimeSet) is on, and always accepts it. Then the dates ts1 and ts2 are written into starttime and endtime of each instance, and the global drift of each column, ddelta0 + ddelta1 + ddelta2, into p_DELTA. Columns past the end of the line keep the last value. On the first line in smooth time, the end date of the last object is also stored as a global drift, so that the end marker gets a date.

Return values. OK when a solution is found; MISSED when the scan went back to the first object without finding one; ABORT, EXIT, ENDREPEAT or QUICK when InterruptTimeSet() reports an event. InterruptTimeSet() is called every ten steps when there are more than 100 objects. It only does something when improvising with real-time MIDI: it listens to incoming MIDI events, which may ask to stop, to repeat, or to play at once (QUICK).

One solution only. The paper (§5.1) stores sol_set1 and sol_set2 in arrays indexed on i to enable backtracking, and BP2 could search for all solutions and let the user choose one. In the code, this search (FINDMORE, Get_choice(), the stack built by Store()) only runs when AllSolTimeSet is TRUE, and FillPhaseDiagram() always sets it to FALSE. Locate() therefore returns the first solution found, after going back as far as needed.

Note 17 — Releasing constraints

When Locate() returns MISSED, the message We must release time constraint(s) is displayed and the line is tried again (label TRY) with fewer constraints. The constraints are first released for the object on which Locate() failed, the one in column iconflict (note 16):

  1. overlapping, if it overlapped the preceding object(s) (shiftconflict > 0), or continuity, if there was a gap (shiftconflict < 0);
  2. if Locate() fails again on the same object, both.

Each release displays a message such as • Releasing overlapping before “f” in sequence #1, naming the object with NameOfInstance() (at the end of TimeSet.c). The next try may fail on another object of the line, whose constraints are then released in the same way. All other objects keep their constraints. Since each try releases at least one more constraint, the number of tries is limited.

If constraints are already released for this object, or if no object was identified, the constraints are released for the whole line, in three steps, as was done before 2026-11-14: first overlapping; then continuity, with overlapping required again; then both. Overlapping released for the whole line is marked LINE_RELEASE (2) instead of TRUE (1), so that the second step withdraws it without withdrawing the overlapping released for single objects. This is needed in smooth time, where some situations are refused whatever the constraints (note 16). If this fails too, SetTimeObjects() returns MISSED and the item is not played (error 37). The paper (§5.4) describes this as an approximate solution obtained by ignoring part or all of the topological properties.

For example, in C4 oscar2-trunc f - oscar2 C4 (with the files of -da.tryMiscObjects), f cannot be placed without overlapping. Releasing overlapping for f only lets oscar2-trunc and oscar2 start after the objects that precede them. When overlapping was released for the whole line, they started at their default positions, overlapping C4 and the silence.

QUICK means that the musician asked, during an improvisation, to play the item at once. Both constraints are released for the whole line, and the line is tried again.

Note 18 — Interactive choices

BP2 asked the user what to do when no solution was found: release continuity, overlapping, or both, decide step by step, or quit. It could also show a solution and ask whether to accept it. This code remains, but it is not active in the console:

  • the block after the label QUEST1 is never reached, because it follows a goto EXIT1;
  • the dialogue after BACKTRACK calls GetCap(), which always answers 'Q' (quit), so it returns ABORT. Locate() only returns BACKTRACK during the search for all solutions (note 16).

For the same reason, the setting Time setting step (StepTimeSet) aborts the time-setting as soon as Next_choice() needs a decision. The interface marks it as “not implemented”.

Note 19 — Global drift in striated time

In striated time, the global drift found by Locate() is added to the structure of time: T[i] += DELTA[i] for every column. After the first column with a drift, a column with no drift takes the value of the previous one, so that all later streaks are delayed together. This is the dotted line of the paper's Fig.4. DELTA is then set back to zero.

If there was any drift (BTflag), the sequences already placed may no longer satisfy their constraints, so the program goes back to STARTAGAIN and processes all lines again from line 0, with the new streaks (note 11). The loop ends when a whole pass creates no global drift. The paper (§6) gives the cost: without global drift, the algorithm takes at most a time proportional to nmax × imax³; with global drifts, nmax² × imax³. In most cases, according to the paper's abstract, it is proportional to nmax × imax.

Note 20 — Interpolating streaks in smooth time

In smooth time, there is no restart. The columns of line nseq that hold an object, a silence or the end marker are marked in p_marked, and their date becomes T[i] + DELTA[i]. Line 0 thus builds the structure of time from the durations of its objects, and the next lines can add dates where they have objects of their own. Dates must not decrease: a date smaller than the previous one, which may happen with small rounding errors, is raised to it. A column of the line that is not marked keeps the date 0; a non-zero date there is an error, reported with trace_timeset and set back to 0.

Columns without a date are never used directly: Calculate_alpha() only uses marked columns to share time among the objects of the next lines (note 12).

Note 21 — Limits of the item

For each line, every instance (index ≥ 2) gives a candidate for tmax: its end date plus its truncated end, and the first instance a candidate for tmin: its start date minus its truncated beginning. Truncated parts are counted so that the limits include the whole objects. MakeSound() uses tmin and tmax to place the item and to draw the pianoroll, and sets with tmax the end of a chunk (ChunkEndTime) when the pianoroll is not shown. DrawItem() uses them for the time ruler of the object graph.

Until 2026-11-15, only the last instance of each line was checked. An object can end after the next ones of its line, for instance oscar2 in item #83 of -da.tryMiscObjects: its volume fades out for 2 seconds after its last NoteOff, which is its pivot. The ruler then stopped before the end of the object, and the chunk ended too early. Legato (note 23) can also extend an object after tmax, which is then updated.

Note 22 — No legato at the end of a chunk

When the item is a chunk other than the last one (PlayChunks && !LastChunk), when all items are produced (AllItems), or when improvising, the last object of each line must not be played legato: it would extend into the next chunk or item. Its articulation is set to 0 if it is positive. Articulations are stored as signed bytes, so a value above 127 is a negative one.

Step 4 — Articulation

Note 23 — Legato and staccato

Once all lines are placed, the articulation a of each instance (_legato(a) gives a positive percentage, _staccato(a) a negative one, at least -99) changes its duration: endtime = starttime + (endtime - starttime) × (1 + a/100), and alpha is multiplied by the same factor. For an object that is not cyclic, beta becomes equal to alpha.

This is done after the constraints are solved, so that legato and staccato change how long objects sound, not where they are placed. Legato is ignored for an object whose end was truncated, since it was truncated to avoid an overlap. If a legato object now ends after tmax (note 21), tmax is moved to its end.

Note 24 — Out-time objects beyond the end

In striated time, an object starting after max_end_time, the date of the last column, is skipped. This happens with an out-time object at the beginning of an item. If no object with a duration was found before it in the list of instances (outtimeevents), its dates are set to 0, so that it is played at the start. A diagnostic message is kept in the code, disabled, to check this case with -gr.koto3.

Note 25 — Cleaning up

All working tables are freed, whatever the result. They are set to NULL before being allocated (note 10), so that a failed allocation can also come here and free only those that exist. TimeSet() does the same with its own tables, which are freed after the label SORTIR (note 6). If an emergency stop was requested in the meantime, the result is ABORT.

Limitations and oddities

  • The tie tables p_Tie_note and p_Tie_event hold char values but are allocated with sizeof(short). This is harmless.
  • tmin is still the start of the first object of each line (note 21), whereas tmax is the latest end of all objects. A later object of the same line, with a long negative pre-roll or a pivot far from its beginning, might start before the first one. It would then start before tmin, and the ruler of the object graph would not reach its beginning.
  • The search for all solutions, the step-by-step mode and the dialogues of note 18 are leftovers of BP2. They could be removed, or made available again through the interface.

Debugging time-setting

Variables at the top of the source files switch on detailed traces in the console's messages:

  • trace_timeset (TimeSet.c) traces the main steps of SetTimeObjects(), the dates T[i] and the limits of the item;
  • trace_fix (TimeSet.c) prints the dates T[i] and time2[i] before and after FixObjectTimings();
  • trace_object_features and check_limits (SetObjectFeatures.c) trace the computation of dilation ratios and limits;
  • trace_diagram and trace_make_silent (FillPhaseDiagram.c) trace the phase diagram and the creation of silent objects;
  • DISPLAY_PHASE_DIAGRAM (TimeSet.c) prints the phase diagram (note 9).

In the settings, Time setting display (DisplayTimeSet) prints every solution found, with the dates, truncations, local and global drifts of each object. Time setting trace (TraceTimeSet) follows the decisions of Locate(): what each object should spend or save, the solution chosen, and the backtracking. Ignore constraints in time setting (NoConstraint) shows the default placement of objects, which helps to tell whether a timing comes from the constraints.

The regression test run-ctests.sh plays every grammar and data project of ctests_git/ and compares the MIDI files and Csound scores produced by two builds of the console. Since every date passes through SetTimeObjects(), it should be run after every change of the code described here.

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

Playing an item: how MakeSound() works

This page is for programmers who want to read, maintain or extend the code that turns a timed item into sound: real-time MIDI, a MIDI file, a Csound score, an event list, and the pianoroll that displays it. All of this is done by one function, MakeSound(), in the console's source file MakeSound.c. The page describes its algorithm step by step.

The code lives in three C files of the console (source/BP3/):

  • MakeSound.c contains MakeSound() and its subroutines;
  • Graphic.c contains PreparePianoroll(), which computes the layout of the pianoroll before the item is played;
  • -BP3.h defines the PianoRoll structure shared by these two files.

Comments of the form // note 12 have been placed in these files. Each one points to the numbered note of this page that explains the code below it. Searching for // note 12 finds every place that note 12 describes. Line numbers are not given because they change with every revision.

Where MakeSound() stands in the production of music

A grammar produces an item: a string of terminal symbols, notes, performance controls and polymetric structures such as {2, C4 D4 E4, F3 G3}. Playing this item takes four steps, all called from PlayBuffer1() in PlayThings.c:

  1. PolyMake() (Polymetric.c) expands the polymetric structure into a regular grid called the phase diagram.
  2. FillPhaseDiagram() places every sound-object, note and control on this grid, and SetTimeObjects() (TimeSet.c) computes the date at which each one starts and ends. Constraints such as overlapping, truncation, pivots and cyclic objects are resolved here.
  3. MakeSound() reads the list of timed objects and sends their events, in chronological order, to the selected outputs.
  4. DrawItem() draws the graph of sound-objects, if requested.

When MakeSound() starts, therefore, all decisions about when things happen have been taken. Its task is to merge the events of all objects into a single chronological stream, to compute the MIDI or Csound values of each event (key, velocity, channel, controls), and to keep track of which keys are sounding so that every NoteOn gets its NoteOff.

The data received by MakeSound()

The main input is the global table p_Instance. Each entry (*p_Instance)[k], for k = 2 to *p_kmax, is a sound-object instance: one occurrence of an object in the item. (Indices 0 and 1 are not used for instances.) Its main fields are:

  • object, called j in the code: what is played. Its value tells what kind of object it is: 
    • j == 0: no object. Terminal 0 is the prolongation _
    • j = 1: silence -
    • 1 < j < Jbol: a sound-object, whose prototype is defined in a -so file. Its events are in (*pp_MIDIcode)[j], a list of MIDI bytes, and possibly in (*pp_CsoundScore)[j], a list of Csound score lines.
    • Jbol ≤ j < 16384: a time pattern, which marks time but produces no sound.
    • j ≥ 16384: a simple note such as C4, whose MIDI key is j - 16384.
    • j < 0: an out-time object (written <<…>>), which has no duration. The code works with -j and sets outtime.
  • starttime, endtime: dates in milliseconds computed by SetTimeObjects().
  • truncbeg, truncend: durations cut at the beginning and at the end of the object, when constraints did not allow it to be played entirely.
  • alpha, beta: dilation ratios. alpha is the ratio between the duration of the object in the item and the duration of its prototype. beta is the ratio applied to the dates of its events. They are equal unless the object is cyclic: a cyclic object stretched by 3 keeps beta = 1 and repeats its periodical part instead (note 4).
  • nseq: the sequence (line of the phase diagram) on which the object is placed. Performance parameters are stored per sequence.
  • channel, velocity, transposition, scale, blockkey, instrument: the values of the performance controls (_chan(), _vel(), _transpose(), _scale(), _ins()…) in force when the object starts.
  • contparameters: the values of continuous parameters (pitchbend, volume, modulation, pressure, panoramic, and Csound parameters), with their start and end values and their mode: fixed, stepwise or continuous.
  • map0, map1, mapmode: key mapping (_keymap()), possibly varying from map0 to map1 during the object.

The other arguments of MakeSound() are tmin and tmax, the limits of the item in time, maxnsequences, the number of sequences, and imaxstreak and p_delta, which are only used to draw the background of the pianoroll.

Overview of the algorithm

Each instance is a stream of events ordered by date. MakeSound() merges these streams, together with the streams of messages generated by continuous controls, into one chronological stream. It does so without sorting the events: it keeps for each instance k the index (*p_inext)[k] of its next event and the date (*p_nextd)[k] of this event, and repeatedly:

  1. picks the instance whose next event comes first, at date t2;
  2. sends the events of this instance that are due at t2 (none of them can be later than the next event of another stream);
  3. saves the position reached in this instance, and goes back to step 1.

This is a k-way merge. Finding the next instance scans all instances, so the cost is proportional to the number of events times the number of instances. It does not require building and sorting a list of all events, and it allows an item to be played while it is computed in real time.

Four dates, all in milliseconds, drive this loop:

  • t0: the origin of the current performance on the output clock;
  • t1: the date of the current event, relative to t0;
  • t2: the date of the next event in any other stream, relative to t0;
  • t3: the date at which the current instance ends, minus its post-roll.

Every event is sent at date t0 + t1. The global Tcurr holds the same date in units of Time_res milliseconds. It is read by the MIDI driver, by scripts and by the functions that write files, so the code updates it whenever t1 changes.

The steps of MakeSound() are:

  1. Preparation: choose the outputs, allocate the working tables, scan the instances to find the first one and the first event of each (notes 1–4).
  2. Pianoroll: compute its limits in time and pitch, and draw its background (note 5).
  3. Outputs: open the Csound score and the MIDI file, tune the MIDI device (notes 6–7).
  4. Performance loop, repeated Nplay times: set the time origin (notes 8–10), then run the scheduler (notes 11–36).
  5. End of the item: release the keys still sounding, append the final silence, close the Csound score, free the memory (notes 37–40).

Notes 41 to 51 describe the subroutines.

Step 1 — Preparation

Note 1 — Choosing the outputs

The function returns at once if a performance is already running (SoundOn) or if the user has pressed PANIC. Without a trace path (--traceout), no graphics can be saved, so they are switched off.

Two local flags decide where the events go:

  • cswrite is TRUE if a Csound score is written. This happens when Csound output is selected and the item is not played in real time (or FileWriteMode is NOW), or when a MIDI file is converted to Csound. In the rest of the code, cswrite selects the Csound branch of every decision: no MIDI event is sent, and CscoreWrite() (CsoundScoreMake.c) writes score lines instead.
  • The global MIDIfileOn is TRUE if a MIDI file is written, under the same condition.

Real-time MIDI is rtMIDI, the event list is EventListOn, and the pianoroll is showpianoroll. The pianoroll is not drawn during a MIDI capture (ItemCapture) or when converting MIDI to Csound. If no output is selected, nothing is done. When several items are produced, ItemNumber counts them, and production stops after MaxItemsProduce items.

The pianoroll is drawn while the item is played, in the same pass: each note is drawn when its NoteOff is sent. It does not require a separate traversal of the events.

Note 2 — Working tables

All tables are Handles (see ConsoleMemory.c), allocated at the start and freed at the end (note 40).

  • Per instance (size MaxObjects):
    • p_inext: index of the next event to send; p_inext1: index of the first event, restored at each performance;
    • p_nextd: date of the next event; Infpos means that the instance is over;
    • p_onoff: TRUE once the instance has started (note 16);
    • p_silence: TRUE when the NoteOns of the instance must be silenced because its end is truncated (note 34);
    • p_istartperiod, p_iendperiod, p_periodgap, p_icycle: the periodical part of cyclic objects (notes 4 and 32).
  • Per MIDI channel and key (16 × 128): 
    • p_keychannel[ch][key]: the number of NoteOns of this key not yet followed by a NoteOff. Several objects can play the same key at the same time, so this is a counter, not a flag;
    • p_last_timeon[ch][key]: the date of the last NoteOn of this key, used to draw the note on the pianoroll and to detect NoteOns that are too close (note 28).
  • Per Csound instrument and key: p_keyinstrument[ins][key], the same counter as p_keychannel, used when cswrite is TRUE.
  • Per channel and continuous parameter: p_active, p_t2cont and p_seqcont describe the continuous controls being sent (note 19).
  • Per sequence:
    • pp_currentparams[nseq]: the performance parameters used by CscoreWrite() (note 17);
    • p_control[nseq]: the streams of continuous MIDI controls (note 19).
  • p_currmapped: the keys changed by key mapping, so that a NoteOff finds the key of its NoteOn (note 51).

Note 3 — Scanning the instances

A first loop over all instances prepares the scheduler. For each instance it:

  • finds the number of events of the object, im, with Find_im(). This is the number of MIDI bytes of the prototype, or the number of lines of its Csound score if that score is played (note 49). A time pattern has no events.
  • sets beta = alpha if the object is played less than twice and its prototype is not of fixed scale. Only a cyclic object keeps a beta different from alpha.
  • finds the first event of the object, (*p_inext1)[k]. The dates of events are obtained by adding the delays between consecutive events, multiplied by beta (EventDelay(), note 46).
  • finds the instance that starts first, kfirstinstance, at date t11, and the start date of the next one, t22. A negative pre-roll moves the start of an object earlier.

The scheduler starts with instance kfirstinstance, t1 = t11 and t2 = t22. As soon as this instance starts, t2 is computed again from all instances (note 16).

Note 4 — Cyclic objects

A sound-object prototype can be declared cyclic: when it must last longer than its prototype (alpha > 1), its events are not stretched; instead, the part that follows cyclicafter is repeated. GetPeriod() (SoundObjects2.c) returns cyclicafter, the date at which the periodical part starts, and objectperiod, its duration.

The scan stores:

  • (*p_istartperiod)[k]: the first event at or after cyclicafter;
  • (*p_iendperiod)[k]: the last event of the first cycle, extended to the following events that are simultaneous with it;
  • (*p_periodgap)[k]: the time between the start of a period and its first event, plus the time between its last event and the end of the cycle;
  • time_nextperiod_start: the date at which the second cycle starts.

For an object that is not cyclic, istartperiod remains -1. Note 32 explains how the scheduler uses these values.

Step 2 — The pianoroll (Graphic.c)

Note 5 — Limits in time and pitch

The pianoroll is an image in which each note is a horizontal bar: its position is its date, its height is its key. Before the first note can be drawn, the size of the image must be known. PreparePianoroll() computes it:

  • The end of the item, tmax, is the largest end date of all instances, increased by the post-roll of sound-objects and by the opposite of a negative pivot. The image covers Nplay repetitions of the item.
  • The range of keys, minkey to maxkey, includes the key of every simple note and the key of every NoteOn in the MIDI codes of sound-objects, after transposition, expansion and key mapping (note 51). For a sound-object whose Csound score is played, the pitch of each score line is converted to a key by CsoundPitchToKey(), according to the pitch format of its instrument: octave point pitch-class (OPPC), octave point decimal (OPD) or frequency in Hertz (CPS). The range is then widened to multiples of 6.
  • The image starts at date 0, or earlier if a pivot or a pre-roll creates negative dates. leftoffset is the x position of date tmin, topoffset the y position of the top of the note scale, and hrect the height of one key (3 pixels). The width is limited to 32000 pixels.

These values are returned in a PianoRoll structure (roll in MakeSound()), which is passed to every function that draws a note. If ShowGraphic is set, PreparePianoroll() also draws the background (DrawItemBackground()) and the note scale (DrawNoteScale()). The field noteoffset is the x position from which notes are drawn. It is set by MakeSound() for each performance (note 10).

Step 3 — Opening the outputs

Note 6 — Preparing the outputs

  • In real time, the clock of the driver is read. When improvising, the time taken to compute the item is recorded in MaxComputeTime if it is the longest so far.
  • If the diapason A4freq is not 440 Hz, TuneMIDIdevice() sends the A4 tuning to all channels of the MIDI device (note 44).
  • For Csound, PrepareCsFile() opens the score. For a MIDI file, PrepareMIDIFile() (MIDIfiles.c) writes its header. In both cases Nplay is set to 1: repetitions are only meaningful in real time.

Note 7 — Resetting the performance parameters

For each sequence, the Csound performance parameters are reset: no key is sounding (level[key] = 0), there is no transposition, and no parameter is active. paramsinstance, the instance whose parameters are currently stored for this sequence, is set to 0 (note 15). All streams of continuous controls are marked inactive (ibm = -1).

Step 4 — The performance loop

Note 8 — Repeating the item

The item is played Nplay times, or forever if SynchroSignal is PLAYFOREVER. Each repetition is called an occurrence. stop() (ConsoleMain.c) is called at the start of each occurrence and before each event: it checks whether the user has clicked STOP or PANIC in the interface, which creates a file in temp_bolprocessor/.

Note 9 — Resetting the instances, truncated beginnings

At the start of each occurrence, every instance is reset: its next event is its first event (p_inext1), it has not started (p_onoff FALSE), and its next date is its start date.

If the beginning of an instance is truncated (truncbeg > 0), the events before the truncation are not played. FirstEventAfterTruncation() (note 47) finds the first NoteOn at or after the truncation, and the time this_gap between them. Starting at a NoteOn avoids sending NoteOffs or controls of notes that were cut. The next date of the instance is then its start date plus this_gap.

All keys are released in the tables of note 2, all switches (pedals) are off, and no continuous control is active.

Note 10 — The time origin

t0 is the date, on the clock of the output, at which date 0 of the item will be played. It depends on the situation:

  • Normally, currenttime = Tcurr × Time_res, the current date of the output. In real time and in MIDI files, MIDIsetUpTime is added once, to give the MIDI device time to receive the first messages.
  • If the item is played as a continuous flow (CyclicPlay) and the driver is already late, the item starts at the current time of the driver.
  • When an item is played line by line in chunks, each chunk starts at the end of the previous one, ChunkEndTime.
  • If t1 is negative (an object starts before date 0 because of a pivot or a pre-roll), t0 is moved later by -t1, so that no event has a negative date.
  • When several items follow each other (improvisation, all items, chunks), t0 is the end of the previous item, LastTime. PianorollShift records this offset so that the pianoroll of each item starts at its own origin.

The pianoroll's noteoffset is set here: it is leftoffset, shifted back if all dates were shifted by -t1.

ChunkEndTime and, in real time, ExpectedEndTime are computed at the first occurrence. ExpectedEndTime is the date at which the item will end, displayed by the clock of produce.php.

For Csound, WriteCsoundTempo() writes the tempo statement at the start of the score (note 45).

Note 11 — The scheduler

The loop while(kcurrentinstance > 0) is the heart of MakeSound(). Each iteration works on one instance, kcurrentinstance:

  1. read the context of the instance (notes 12–15);
  2. if the instance has not started yet, start it: send its initial controls, script and switches (notes 16–20);
  3. send its events while t1 ≤ t2 and t1 ≤ t3 (notes 21–33);
  4. record where it stopped, or that it is over (note 34);
  5. send a message of a continuous control if one is due (note 35);
  6. find the next instance or control (note 36).

The loop ends when NextInstance() returns 0: no instance has an event left.

Here is an example with C4 {D4, E4 F4} at 60 beats per minute. Instance 2 is C4 (0–1000 ms), 3 is D4 (1000–2000), 4 is E4 (1000–1500), 5 is F4 (1500–2000). The next dates of the instances are 0, 1000, 1000 and 1500.

  1. Instance 2 starts, and t2 becomes 0, its own date. It sends NoteOn C4 at 0. Its next event, the NoteOff at 1000, is later than t2, so it is suspended with next date 1000.
  2. Instances 2, 3 and 4 now have the earliest date, 1000. The first one in the table is chosen: instance 2 sends NoteOff C4 at 1000 and is over.
  3. Instance 3 sends NoteOn D4 at 1000 and is suspended until 2000. Instance 4 sends NoteOn E4 at 1000 and is suspended until 1500.
  4. At 1500, instance 4 comes before instance 5: it sends NoteOff E4, then instance 5 sends NoteOn F4.
  5. At 2000, instance 3 sends NoteOff D4, then instance 5 sends NoteOff F4.

At equal dates, instances are taken in the order of the table, which is the order of the item. A note that ends is therefore released before the next note of the same sequence starts, as at step 4.

Note 12 — Context of the current instance

Each time the scheduler comes back to an instance, it reads its parameters: object j, scale, block key, channel (converted by ChannelConvert(), note 49), sequence nseq, dilation ratios. A negative j indicates an out-time object (see “The data received by MakeSound()”).

Note 13 — Number of events

The events of an instance are indexed by ievent, from 0 to im - 1:

  • for a sound-object whose MIDI codes are played, ievent is the index of a byte in (*pp_MIDIcode)[j]. A NoteOn takes three entries (status, key, velocity). Each entry has a time field, the delay in milliseconds since the previous entry, before dilation;
  • for a sound-object whose Csound score is played, ievent is the index of a line of the score, (*pp_CsoundScore)[j];
  • a simple note has im = 6: two “virtual” messages of three bytes, a NoteOn at ievent = 0 and a NoteOff at ievent = 3 (note 33).

The pre-roll and post-roll of the prototype (ObjectPreRoll(), ObjectPostRoll(), note 46), its cyclic period (note 4), and its strike again setting (note 28) are also read here.

Note 14 — End date and duration

The instance must stop at t3, its end date minus the post-roll of its prototype. objectstarttime is its start date minus the truncated part, and earlier by a negative pre-roll. objectduration = t3 - objectstarttime is used to spread continuous controls and key mappings over the object. A negative or unreasonably long duration (over 500 seconds) indicates an error in the time-setting. It is reported, and the duration is set to 0.

Note 15 — Restoring the Csound parameters of a resumed object

The Csound parameters (note 17) are stored per sequence, not per instance. If an object is interrupted by the start of another object on the same sequence, its parameters are replaced. When the scheduler comes back to the first object, its own parameters are therefore copied back with SetObjectParameters(). paramsinstance records which instance the parameters of the sequence belong to, so the copy is only made when it has changed. Example: in _volumecont _volume(30) a C4 … _volume(127), if sound-object a lasts longer than its time slot, its events after the start of C4 keep the volume variation of a.

Note 16 — Starting an instance

The first time the scheduler comes to an instance, (*p_onoff)[k] is FALSE. The instance is then started:

  • it is added to the event list if one is written (AddEventToList());
  • its MIDI channel is computed by MIDIchannel() (note 49);
  • unless it is out-time, SendInitialControls() sends its volume, panoramic, pitchbend, pressure and modulation on this channel if they have changed (note 42);
  • t2 is computed again, since the start of this instance may change which stream comes next (NextInstance() and NextControlDate(), note 48).

Note 17 — Csound parameters

The parameters of the instance (contparameters) are copied to those of its sequence (pp_currentparams[nseq]->params) by SetObjectParameters(). CscoreWrite() reads them to compute the parameter fields of each score line: for a continuous variation, it interpolates between startvalue and endvalue (or along a table of points) according to the date of the event within the object.

The table of a sequence is created with only the five MIDI parameters (IPANORAMIC + 1), and enlarged here to MaxParameters + IPANORAMIC + 1 entries, adding the parameters declared in the Csound instruments. The table of an instance always has this size, since SetObjectParams() (SetObjectFeatures.c) creates it that way. A different size is reported as an error.

SetObjectParameters() marks a parameter inactive in these cases, so that CscoreWrite() uses its default value:

  • volume or panoramic, when the prototype does not accept them;
  • an additional parameter without a value;
  • a continuous MIDI parameter set on another channel than the object's.

Note 18 — Scripts

An object can carry script commands, such as _script(wait for C3 channel 1) or _script(MIDI send Start). ExecuteScriptList() executes them in order when the object starts, through ExecScriptLine() (Script.c). A command can make the performance wait. The time spent waiting is added to LapWait, and WaitEndDate is shifted accordingly.

Note 19 — Continuous MIDI controls

A continuous variation of a MIDI parameter, such as _pitchbend(0) _pitchcont … _pitchbend(200), cannot be sent as a single message: it is sent as a stream of messages at regular intervals during the object. For each of the five MIDI parameters (pitchbend, volume, modulation, pressure, panoramic) whose mode is CONTINUOUS, a stream is set up in (*p_control)[nseq].param[index]:

  • starttime, duration: the start date and duration of the object;
  • startvalue, endvalue, and possibly a table of points point with imax entries;
  • channel: the channel on which the variation was set;
  • ibm: the number of messages, computed by Findibm() from the duration and the rate (messages per second) set for this parameter and channel in the settings; ib: the number of messages already sent.

Only one stream per channel and parameter can be active at a time. (*p_active[ch])[index] tells whether a stream is active, (*p_seqcont[ch])[index] on which sequence it is, and (*p_t2cont[ch])[index] the date of its next message. If a stream was still active on this channel (it may not have ended because of rounding), its last message is sent first. The new stream sends its first message at once, and the date of its next message may become the new t2.

When a Csound score line of the object is played (PlayCsoundLine()), these streams are skipped: Csound variations are handled by CscoreWrite() (note 17). The messages of the streams are sent by SendControl() (notes 35 and 50).

Note 20 — Switches and dilation ratio

Switches are the MIDI controllers 64 to 69, including the sustain pedal (64), set with _switchon() and _switchoff(). SendSwitches() (note 43) sends those that have changed when the object starts. The state of the switches of each channel is kept in currswitchstate[ch], one bit per switch.

If the prototype asks for it, SendDilationRatio() (note 44) sends the dilation ratio beta of the object to a MIDI controller. This allows a synthesizer to adapt the sound to the speed of the performance.

Note 21 — Sending the events of an instance

The inner loop sends the events of the current instance as long as:

  • t1 ≤ t2: no other stream has an event before this one;
  • t1 ≤ t3: the instance has not reached its end;
  • ievent < im: the instance has events left.

When two streams have events at the same date, the current instance goes first, which avoids switching between instances for simultaneous events. Each event is processed by notes 22 to 31, then t1 and ievent are advanced to the next event (notes 32 and 33).

Note 22 — End of a cyclic object

When a cyclic object reaches its end (t1 ≥ t3) and integer cycles are not forced, the last cycle is incomplete. If the last event of the object has been reached, all keys still sounding on its channel are released, and the loop moves on to the end-of-period test (note 32).

Before each event, howmuch is computed: the fraction of the object already played, from 0 to 1. Key mapping uses it to move progressively from map0 to map1 (note 51).

Note 23 — Csound score lines of a sound-object

If the prototype has a Csound score and a Csound score is written, the line ievent is passed to CscoreWrite() with its date t0 + t1 and the dilation ratio beta, which scales its duration. If the end of the object is truncated, cut_the_end is the part of this line that falls after the truncation, and its duration is shortened accordingly. No line is written while the object is silenced (note 34).

Note 24 — Decoding an event

Otherwise, the event is a MIDI message. Its status byte c0 is read:

  • for a sound-object, from its MIDI codes;
  • for a simple note or a time pattern, it is NoteOn if ievent == 0, else NoteOff.

MIDIchannel() separates the channel from the status byte (note 49). localchan is the channel on which the message is sent: the one in the MIDI code, the default channel of the prototype, or the channel of the object.

For a NoteOn or NoteOff, the key c1 and the velocity c2 follow. They are read from the next two bytes for a sound-object, or computed for a simple note: GoodKey(j) and velocity 127, which ClipVelocity() will scale. A time pattern produces nothing: its events are skipped.

Note 25 — Transposition and expansion

The key is transposed (_transpose()) and expanded (_keyxpand()) by TransposeAndExpand(). The order of these two operations depends on the order in which they were written in the item (transposefirst). GoodKey() brings the key of a simple note into the range 0–127 by octaves, with an error message.

Note 26 — NoteOff

A NoteOff, or a NoteOn with velocity 0, which MIDI treats as a NoteOff, is handled as follows:

  1. If key mapping changed the key of the matching NoteOn, RetrieveMappedKey() returns the mapped key (note 51).
  2. The counter p_keychannel[localchan][c1] is decreased. If it was already 0, the NoteOff is ignored: its NoteOn was merged with another one (note 28) or not played.
  3. The NoteOff is only sent when the counter reaches 0, i.e. when no other object is still holding this key. In Csound, every NoteOff is passed to CscoreWrite(), which finds the matching NoteOn and writes the score line with its duration. The counter p_keyinstrument of the instrument is decreased.
  4. In MIDI, SendNoteOffAndDraw() sends the NoteOff and draws the note on the pianoroll from its NoteOn date (note 41).

Note 27 — NoteOn: key mapping

If key mapping applies to this object (always for simple notes, according to the prototype for sound-objects), MapThisKey() gives the key to play (note 51). The pair (original key, played key) is stored by StoreMappedKey() after the NoteOn is sent, so that the NoteOff of the original key releases the played key. The counter of the key is then increased.

Note 28 — NoteOn: repeated keys

Two problems arise when a key is struck while it is already sounding:

  • MIDI cannot play the same key twice on the same channel. If the prototype (or the settings) asks to strike again (StrikeAgainOf(), note 46), a NoteOff is sent before the new NoteOn. Otherwise the NoteOn is not sent (strike = FALSE), and the key goes on sounding.
  • Two NoteOns of the same key very close in time are often an artefact of the polymetric structure, for example a note ending and the same note starting a few milliseconds later. If the key is still sounding and the delay since its last NoteOn (delta_timeon) is not more than MaxDeltaTime, the second NoteOn is skipped, and the two notes are merged. MaxDeltaTime is 20 ms, or twice the quantization if quantization is on.

In Csound (cswrite), NoteOns are never merged, and no NoteOff is written before a repeated key, since a score can contain overlapping notes of the same key. If strike again is off, however, the repeated NoteOn is not written either.

Note 29 — NoteOn: velocity and sending

The velocity is computed by ClipVelocity(): the velocity in the MIDI code (or 127 for a simple note) is multiplied by the velocity of the object (_vel()) divided by 127. It can be replaced by the value of a parameter Kx controlled from a MIDI input (velcontrol), and randomised by _rndvel(). The result is limited to 127.

The NoteOn is then sent by SendMIDIevent(), or passed to CscoreWrite(). Its date is stored in p_last_timeon for the pianoroll, and in starttime[key] of the sequence for Csound. No NoteOn is sent while the instance is silenced (note 34). In Csound, the note is drawn on the pianoroll by CscoreWrite() when it writes the score line.

Note 30 — Advancing time after a note

Reading a NoteOn or NoteOff of a sound-object consumed three bytes: ievent was increased twice. t1 is advanced by the delays of the two data bytes, multiplied by beta. (These delays are normally 0.) The delay of the next status byte is added in note 33.

Note 31 — Other MIDI messages

Other messages of sound-objects are sent as they are, with the channel of the object added to channel messages:

  • three-byte messages, such as control changes or pitchbend, with NORMAL_EVENT;
  • two-byte messages, such as program change or channel pressure, with TWO_BYTE_EVENT;
  • single bytes, such as Start, Stop or Continue, with RAW_EVENT.

The timing clock byte (0xF8) is not sent: prototypes use it internally to create silences. In Csound, these messages are ignored.

Note 32 — New period of a cyclic object

When a cyclic object reaches the last event of its period (ievent ≥ iendperiod), the next event is the first event of the period (istartperiod). Its date is the start of the next period plus periodgap, and time_nextperiod_start moves forward by one period. (*p_icycle)[k] counts the cycles.

A new period is played as long as it starts before t3 and the number of cycles ncycles computed by the time-setting has not been reached. Unless the prototype forces an integer number of cycles, send_more allows the last, incomplete cycle to be played: it is cut at t3 (note 22).

Note 33 — Advancing to the next event

ievent is increased, and t1 is advanced by the delay of the new event, multiplied by beta:

  • for a sound-object, the delay of the next MIDI byte or Csound line (EventDelay(), note 46);
  • for a simple note or a time pattern, 1000 ms. The NoteOff of a simple note therefore comes beta × 1000 ms after its NoteOn: a note lasts one beat at the tempo of the item, scaled by its dilation ratio.

If the new date is later than t2 or t3, the inner loop ends.

Note 34 — Suspending or ending the instance

When the inner loop ends, one of two things has happened:

  • The instance has events left (ievent < im): it is suspended. (*p_inext)[k] records its next event and (*p_nextd)[k] the date of this event. If this date is beyond the end of the object, the end of the object was truncated by the time-setting: the next date is set to t3, and if truncend > 0, the instance is marked silenced. Its remaining events will still be read, so that every NoteOff is sent, but its NoteOns will not.
  • The instance has no events left: (*p_nextd)[k] = Infpos, and it will never be chosen again.

Note 35 — Sending a message of a continuous control

If the next event is a message of a continuous control (icont and chancont designate it), SendControl() sends it (note 50). This part is skipped for Csound, where continuous parameters are handled in the score (note 17).

Note 36 — Finding the next event

NextInstance() returns the instance whose next date is the earliest, and its date in t2obj. NextControlDate() then looks for an active continuous control whose next message comes at or before this date (note 48):

  • If there is one, its message is sent (back to note 35), and the search starts again.
  • Otherwise, the scheduler goes back to the instance found, with t1 = its next date (note 11). t2 is set to the date of the next event among all streams, including this instance, so the instance will at least send one event before t1 ≤ t2 fails.

Step 5 — End of the item

Note 37 — After the last occurrence

In real time, an Active Sensing message is sent, which keeps the MIDI driver active so that it can still handle MIDI input. If a pianoroll is displayed, the function jumps to OUTGRAPHIC, which skips the release of keys.

Note 38 — Exits

Three labels handle the end of the function:

  • OVER is reached after an error or an interruption. ENDREPEAT is a normal end. STOP or PANIC return ABORT, and the message “(Stopped playing)” is displayed.
  • OUTGRAPHIC: unless a pianoroll is displayed or Csound is written, ReleaseKeysAndSwitches() (note 43) sends a NoteOff for every key still sounding and switches off every pedal still on. When improvising, playing chunks or playing cyclically, the next item continues the music, so this is only done if the result is RESUME.
  • GETOUT frees the memory and returns.

Note 39 — Silence at the end of an item

An item can end with a silence, for example C4 D4 - -. No event marks the end of this silence, so the next item would start too early when several items are played in a row (improvisation, chunks). The duration of the final silence, add_time, is the difference between the end of the last instance and the end of the last instance that is not a silence. It is materialised:

  • in MIDI, by two NoteOns of key 0 with velocity 0 (i.e. two NoteOffs), at the start and at the end of the silence;
  • in Csound, by a line i1 date duration 0.00 0 0 ; silence.

Note 40 — Closing the Csound score and freeing memory

For Csound, LastTime is advanced by the duration of the item, so that the next item follows it in the score. Unless several items are written in a row, the section ends with an s line. (When the score belongs to a sound-object prototype, prototype.php deletes this line.)

All tables of note 2 are freed. SoundOn is reset. If a pianoroll was displayed, Tcurr is restored to its value at the start of MakeSound().

Subroutines

Note 41 — Sending a MIDI event

All MIDI output goes through SendToDriver() (MIDIstuff.c), which sends the event to real-time MIDI, the MIDI file and the event list, and handles microtonality (scale, blockkey). It takes a MIDI_Event structure and a date in milliseconds. Three helpers fill this structure:

  • SendMIDIevent(type, status, data1, data2, kinstance, scale, blockkey, date, nseq, p_rs) builds the event and sends it. type is NORMAL_EVENT, TWO_BYTE_EVENT (status and data2), or RAW_EVENT (a single byte, given in both status and data2: real-time MIDI reads the first, MIDI files the second). kinstance, scale and blockkey are only needed for NoteOn and NoteOff.
  • SendControlChange(chan, control, value, date, nseq, p_rs) sends a control change.
  • SendNoteOffAndDraw() sends a NoteOff and, if the pianoroll is displayed, draws the note from the date of its NoteOn, stored in p_last_timeon.

p_rs points to the running status, which lets MIDI omit a status byte identical to the previous one. It is reset to 0 wherever the next message must carry its status byte.

Note 42 — Initial controls of an object

SendInitialControls() sends, at the start of an object, the values of volume, panoramic, pitchbend, pressure and modulation of the object, if they differ from the last value sent on its channel (p_Oldvalue). A value is not sent if a continuous control of the same parameter is active on this channel: the stream has priority. Volume and panoramic can be taken from a parameter Kx controlled from a MIDI input. Pitchbend and modulation are sent as 14-bit values (LSB and MSB). The flags ChangedVolume, ChangedPitchbend, etc. record that these parameters have been changed, so that they can be reset later.

Note 43 — Switches

SendSwitches() compares the state of the switches of each channel required by the object with currswitchstate[ch], and sends the six controllers (64–69) of the channels where they differ. If PedalReleaseDefault is set, the switches that remain on are released and pressed again at the start of each object, which renews the sustain as a pianist would.

ReleaseKeysAndSwitches() is called at the end of the item. It sends a NoteOff (NoteOn with velocity 0) for each key whose counter is not zero, and switches off the switches that are on.

Note 44 — Dilation ratio, tuning, MPE

  • SendDilationRatio() converts beta, in the range 0.01 to 100, to the range 0–127 on a logarithmic scale (32 × log10(beta) + 64) and sends it to the controller chosen in the prototype.
  • TuneMIDIdevice() converts the diapason A4freq to a number of semitones and cents relative to 440 Hz, and sends them on every channel with the RPN for A4 tuning (controllers 101/100, then data entry 6/38).
  • SetUpMPEreceiver() would configure the receiver for MPE (MIDI Polyphonic Expression): mode 3, a lower zone on channels 2–16, and a pitchbend sensitivity of ±2 semitones. It is not used at present: its call is disabled in MakeSound(), because this setup proved unnecessary and created noises with some synthesizers.

Note 45 — Csound tempo

WriteCsoundTempo() writes a tempo statement t … 60 at the start of the Csound score. With several items in a row, only the first one gets it. If the score can no longer be written (it may have been closed by another application), the file is reopened and the statement is written again.

Note 46 — Properties of sound-object prototypes

  • ObjectPreRoll(), ObjectPostRoll() and ObjectPivot() return the pre-roll, post-roll and pivot position of prototype j, in milliseconds. Each is either a fixed value (FIXVALUE) or a value that scales with the object, multiplied by beta.
  • StrikeAgainOf() returns the strike again setting of the prototype, or that of the project if the prototype does not set it (note 28).
  • EventDelay() returns the delay, before dilation, between event i - 1 and event i: from the Csound score of the prototype if it is played, else from its MIDI codes.

Note 47 — First event after a truncation

FirstEventAfterTruncation() walks through the MIDI codes of the prototype, adding the delays, until it finds a NoteOn with a non-zero velocity at or after the truncated date truncbeg. It returns its index and, in *p_gap, the time between the truncation and this NoteOn. If there is no such NoteOn, it returns im, and the instance plays nothing.

Note 48 — Next instance, next control

  • NextInstance() returns the instance with the smallest next date p_nextd, and this date. If several instances have the same date, the first one in the table is chosen. When called from the scheduler with p_silence, it also resets the silence flag of the instances it passes, except the current one.
  • NextControlDate() looks among the active continuous controls of all channels for one whose next message comes at or before *p_t2. If it finds one, it returns TRUE with its date in *p_t2, its parameter in *p_icont and its channel in *p_chancont.

Note 49 — Channels, instruments, MIDI or Csound

  • ChannelConvert() returns the channel number of an instance, 1 to 16 when set. A value of 128 or more means that the channel is given by a parameter Kx (_chan(K3)), whose value may come from a MIDI input.
  • MIDIchannel() returns the channel (0–15) on which an event is sent. For a channel message of a sound-object, it removes the channel from the status byte *p_c0, then uses the default channel of the prototype if it has one, or the channel of the message if the prototype says so. Otherwise it uses the channel of the object. In Csound, the channel is 0.
  • ThisInstrument() returns the Csound instrument of an instance: the one set by _ins(), the one assigned to the prototype, or, if the prototype's score defines its own instruments, the instrument of the score line being played. InstrumentIndex() returns its index in the table of instruments of the -cs file.
  • PlayCsoundLine() is TRUE if a Csound score is written and the prototype has a Csound score: then its score is played rather than its MIDI codes. PlayMIDIcode() tells whether the prototype has MIDI codes. Find_im() returns the number of events accordingly.

Note 50 — Streams of continuous controls

  • Findibm() returns the number of messages of a stream: its duration multiplied by the rate set in the settings for this parameter and channel (messages per second).
  • SendControl() sends message ib of a stream. Its value is given by GetTableValue() at the position ib / ibm, and its date is t0 + starttime + duration × ib / ibm. Pitchbend and modulation are sent as 14-bit values, pressure as a two-byte message, volume and panoramic as control changes, on the controllers chosen in the settings. Then ib is increased and the date of the next message is stored in p_t2cont. When the stream is complete, it is deactivated. If another sequence has a stream of the same parameter on the same channel, that stream takes over from the current date.
  • GetTableValue() returns the value at position alpha (0 to 1): a linear interpolation between the start and end values, or between the points of a table if the variation was defined by one.

Note 51 — Key mapping

A key map, set by _keymap(), defines a linear mapping from the range of keys p1–p2 to the range q1–q2. Keys outside the first range are unchanged.

  • KeyImage() applies a mapping to a key, rounding to the nearest key.
  • MapThisKey() chooses the mapping according to mapmode: none, a fixed map, or, in continuous mode, a map interpolated between map0 and map1 according to howmuch, the fraction of the object already played.
  • StoreMappedKey() records the pair (original key, played key) for an instance and channel, and RetrieveMappedKey() finds it, and deletes it, when the NoteOff of the original key arrives. Without this table, a NoteOff mapped with a different howmuch would release the wrong key.

Limitations and oddities

  • The variables ievent, im and localchan are reused from one instance to the next in a few places. For example, ThisInstrument() is called with the ievent of the previous instance when an instance is resumed. This has no effect in the tested cases, but care is needed when changing these parts.
  • For a time pattern, im is not set in the scheduler. It keeps the value of the previous instance.
  • ContinuousParameter(), in MakeSound.c, is not used at present. It is kept for later use.
  • SendDilationRatio() may be wrong when the controller number is less than 64, as a comment in the code says.
  • The time spent by scripts waiting (note 18) is measured with clock(), i.e. processor time, not wall-clock time.

Debugging a performance

Three variables at the top of MakeSound.c switch on detailed traces in the console's messages:

  • trace_makesound traces every step of the scheduler: the dates t1, t2, t3 of each event, the instance chosen, cycles and truncations;
  • trace_missed_noteoff reports NoteOffs that found no sounding key;
  • trace_maps traces key mappings.

In the settings, Trace NoteOn/NoteOff (TraceNoteOn) displays every note sent with its channel and date. It also displays the NoteOns found too close to the previous one of the same key (note 28), marked with ?. The regression test run-ctests.sh plays every grammar and data project of ctests_git/ and compares the MIDI files and Csound scores produced by two builds of the console. It should be run after every change of MakeSound(). It does not test real-time MIDI (STOP, PANIC, scripts waiting for MIDI input), which must be checked by hand.

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

Importing MusicXML: how the converter works

This page is for programmers who want to read, maintain or extend the code that converts MusicXML scores into Bol Processor data. It describes the algorithm step by step. The musical side of the import (options, ornaments, examples) is described on the page Importing MusicXML scores.

The code lives in three PHP files of the interface:

  • data.php receives the uploaded file, scans it, splits it into measures and displays the options;
  • _musicxml.php contains the converter itself, convert_musicxml(), and its helper functions;
  • _basic_tasks.php contains the arithmetic of fractions and the final cleanup of the score.

Comments of the form // note 12 have been placed in these files. Each one points to the numbered note of this page that explains the code below it. Searching for // note 12 finds every place that note 12 describes. Line numbers are not given because they change with every revision.

What the converter produces

A MusicXML document describes a score part by part, measure by measure, and inside a measure voice by voice. The Bol Processor represents the same music as a sequence of polymetric expressions:

  • {4, C5 D5 E5 F5} is a sequence of four notes lasting 4 beats in total. Each note gets an equal share, here one beat.
  • {2, F3, A3} contains two fields separated by commas. They are played simultaneously, both lasting 2 beats: this is a chord.
  • Without a ratio, C5 D5 takes one beat per symbol. An integer or a fraction in a sequence is a silence of that many beats, and - is a silence of one unit.
  • A5& starts a tie and &A5 ends it. The console joins them into a single note when it plays the item.
  • Performance controls such as _tempo(3/2), _vel(64), _chan(2), _legato(20) or _switchon(64,1) apply to what follows them.

Each measure of the score becomes one polymetric expression. It contains one field per part, and each part contains one field per voice. Here is a small piano score in F major at 90 bpm, with two voices, a mordent, a triplet, a chord and a tie across the bar line:

[—1—] {_tempo(3/2) _vel(64) {4,C5 {1/8,D5 E5} {7/8,D5} {1,Eb5 F5 G5} A5&,1 {2,F3,A3} 1}}
[—2—] {_tempo(3/2) _vel(64) {4,{4,&A5 1},{4,Bb2}}}

In measure 1, the upper voice is the first field: C5, D5 with an upper mordent, a triplet of eighth notes, then A5 tied to the next measure. The lower voice is the second field: a one-beat rest, the chord F3–A3 for two beats, and a one-beat rest that the converter added to complete the measure. The measure lasts 4 beats, and _tempo(3/2) sets the metronome to 90, since the Bol Processor counts 60 beats per minute by default.

The whole difficulty of the conversion comes from one property of polymetric expressions: all fields of an expression are stretched or compressed to the same duration. A voice that is shorter than the others would therefore be played more slowly. The converter must measure every voice exactly, with fractions rather than floating-point numbers, and pad it with silence where necessary. Most of the code described below keeps track of dates for this purpose.

Overview of the process

  1. Scan (data.php): read the file line by line, list the parts, collect divisions, keys and tempo statistics, detect the features that require options, and split the score into a table $this_score[section][measure][part] of XML lines. Optionally remove hidden playback notes.
  2. Convert (convert_musicxml()): for each section, each repetition, each measure and each selected part: 
    1. pass 1 reads the XML lines and builds a list of events (notes, rests, chords, backups, tempo changes);
    2. pass 2 turns this list into polymetric text, voice by voice, keeping exact dates;
    3. the measure is closed: voices are padded to the same length, tempo and dynamics are written, and the ornaments, arpeggios and pedal commands that pass 2 left as placeholders are realised.
  3. Clean up (data.php and _basic_tasks.php): simplify the text and add the header comments that list the options used.

Step 1 — Scanning the file (data.php)

Note 1 — Reading the file as lines

The import takes two submissions of the form. The first one uploads the file, saves it as temp.musicxml in the user's temporary folder, and displays the parts and options found in it. The second one ($reload_musicxml is true) converts the score with the selected parts and options. convert_musicxml() produces nothing on the first submission.

The file is not parsed with an XML parser. Its content is split into lines (\r is first replaced with \n), and every tag is detected with strpos() on the current line. This works because score editors write MusicXML with one element per line. A few elements whose content needs decoding (instrument names, pedal attributes) are read with simplexml_load_string() applied to their single line. Only uncompressed files (.musicxml, .xml) in the partwise format are converted.

Note 2 — The list of parts

Each <score-part id="…"> in the <part-list> becomes a checkbox. Its <instrument-name> and <midi-channel> are stored in $instrument_name[] and $midi_channel[], indexed by the part identifier. For each part the user also chooses whether dynamics are rendered as velocity (_vel()) or volume (_volume()). On the first submission only the first part is selected.

Note 3 — Divisions and key

Inside <attributes>, the scan stores for each part:

  • $divisions[part]: the number of divisions per quarter note. Every <duration> of the score is an integer number of divisions, so all dates and durations in the converter are counted in divisions and divided by this number at the end to obtain beats (quarter notes).
  • $fifths[part] and $mode[part]: the key signature, used to compute the neighbour notes of ornaments (note 37).

A single value is kept per part (the last one read), which assumes that divisions do not change in the middle of a part.

Note 4 — Tempo statistics

All metronome values of the score are collected to display their minimum, average and maximum. Values are read from <sound tempo="…"/> (quarter notes per minute) and, depending on the tempo option, from the <per-minute> of printed metronome marks, converted to quarter notes per minute according to their beat unit (note 19). The user may type new minimum, average and maximum values, which are applied to every tempo during the conversion (note 9).

Note 5 — Detecting features

Flags such as $found_trill, $found_mordent, $found_turn, $found_fermata, $found_arpeggio, $found_breath, $found_slur and $found_pedal[] record what the score contains, so that the form only displays the relevant options. The flags $found_hidden_notes and $found_playback_notes concern notes that are not printed (see note 7).

Note 6 — Measures, sections and repetitions

Every line between <measure number="…"> and </measure> is appended to $this_score[$section][$i_measure][$part][]. Directions and attributes inside measures are kept, since the converter reads them in pass 1.

Repeat bar lines split the score into sections. A <repeat direction="forward"/> starts a new section. A <repeat direction="backward"/> sets $repeat_section[$section] = 2, and the next measure opens a new section. The converter plays every section $repeat_section[] times. Volta brackets (<ending>) are not interpreted: a first ending inside a repeated section is played on both passes.

Measure numbers are taken from the number attribute. Numbers that are not integers (e.g. "X1" for an implicit or pickup measure) are kept as strings. The converter labels them with the number of the preceding measure (note 11). For this reason the measures of a section are never sorted.

Note 7 — Hidden notes

Some editors, notably Finale, export their own playback of trills, tremolos and similar signs as extra notes marked print-object="no", placed in additional voices reached with <backup> and <forward>. Finale marks them with print-spacing="no" as well. Importing them would double the ornaments that the converter realises itself. Their odd durations (such as 115/512 of a quarter note) also create huge ratios in polymetric expressions, which disturb the timing of the other parts.

The option “Ignore hidden notes” is checked by default when the score contains such playback notes (print-spacing="no"). remove_hidden_notes() is then applied to the lines of each part in each measure, before conversion:

  1. The lines are grouped into segments: note (a visible note), hidden (a note with print-object="no"), backup, forward and other (directions, attributes, etc.). A segment runs from the opening tag to its closing tag, and its <duration> is read. A hidden note in a chord or a grace note has no duration of its own.
  2. Segments are grouped into voices: a new voice starts at each <backup>.
  3. If no visible note of the measure carries an ornament that the converter realises (<trill-mark, <wavy-line, mordents or turns, unless these are ignored), the measure is returned unchanged. In that case the hidden notes are the only rendering of something the converter ignores, such as a tremolo or repeated notes written as an abbreviation, and they must be played.
  4. A voice (other than the first) that contains no visible note is deleted, except for its other lines. Its net time advance (durations minus its own backup) is accumulated in $shift. The duration of the next <backup> is reduced by $shift, or replaced with a <forward> if it becomes negative, so that the following voices still start at the right date.
  5. In a voice that also contains visible notes, each hidden note is replaced with a <forward> of the same duration. Consecutive forwards are merged. A trailing forward is kept, otherwise the voice would be shorter and stretched (see “What the converter produces”).

The number of removed notes is written in the header of the data, e.g. “// Ignoring 1989 hidden notes”.

Note 8 — Cleaning up the result

The text returned by convert_musicxml() is simplified by cleanup_score() (_basic_tasks.php), a series of string replacements and regular expressions:

  • spaces are normalised and empty braces {} are deleted;
  • {{…}} becomes {…} and {---} becomes ---;
  • fields that contain only silences are deleted, since a silent field adds nothing to a polymetric expression;
  • {2/3} becomes 2/3, and {33/8,--} becomes the silence 33/8;
  • empty measures created by repetitions are deleted.

Then data.php replaces the slur placeholders _legato_ and _nolegato_ with _legato(n) and _legato(0), where n is the percentage chosen by the user. normalize_rests() merges consecutive silences into a single number, and normalize_ampersand() deletes tie signs left on silences. The header comments listing the options are written above the score. The first _scale() found on the page before the import is kept at the beginning of the new score.

Step 2 — The conversion (convert_musicxml)

Note 9 — Changing the metronome

If the user has entered new values for the minimum, average and maximum tempo, every tempo read in the score is transformed by a function f that maps the three current values to the three new ones. quadratic_mapping() computes the parabola f(x) = ax² + bx + c through the three points and returns its derivative at the minimum and maximum. If both derivatives are positive, f is monotonic between the extreme tempi and is used. Otherwise a piecewise linear mapping is used: one segment from minimum to average, another from average to maximum. Either way, the order of tempi is preserved.

Note 10 — Sections and repetitions

The outer loops run over the sections, then over the repetitions of each section. At the start of a section, the default tempo is the current tempo, so that a tempo set in the previous section carries over. The tie flags are reset at each repetition.

Note 11 — Measures

For each measure the converter writes the optional comment [—n—] (option “Insert measure numbers”), and _legato(n) before the last measure if “Extend duration of last measure” is set. It then opens the brace of the measure. An implicit measure gets a label combining the number of the preceding measure and its own number (e.g. 12-X1).

Note 12 — Parts

Parts that are not selected are skipped. For each selected part, the state is reset: date counters, fermata tables, breath locations and the event list. The diatonic scale of the part is computed from its key signature (note 37). The first tempo of the part is the last tempo of the previous measure ($final_metronome), or the default tempo of the section.

Note 13 — Pass 1: from XML lines to events

Pass 1 reads the lines of one part in one measure and fills the array $curr_event[$score_part][$j]. Each event has:

  • type: seq (a note or rest played after the previous one), chord (a note sounding with the previous one), back (a backup, which starts a new voice) or mm (a tempo change);
  • note: the note name in English convention, - for a rest, or empty for a null event;
  • p_dur/q_dur: the duration as a fraction of divisions;
  • optional attributes: fermata, slur, ornament, turn, arpeggio, staccato, breath_mark, sustain, sostenuto, soft, forward, value (the tempo of an mm event), etc.

A <note> line sets $note_on. The lines up to </note> set flags and values, and the event is completed and stored at </note>. Pass 1 also keeps the date $p_date/$q_date of the current voice, and the running sum $sum_durations of the part, which is used to locate breath marks.

Note 14 — Exact durations of tuplets

MusicXML durations are integers. In a tuplet the editor must round them: with 1024 divisions per quarter note, a triplet eighth note lasts 1024/3 divisions, written as 341 or 342. The Bol Processor would then see three notes of slightly different lengths, and the polymetric expression would get a huge ratio. At </note>, if the note has a <time-modification>, exact_tuplet_duration() recalculates the duration from the graphic type, the dots and the tuplet ratio:

duration = divisions × value(type) × normal / actual × (2^(d+1) − 1) / 2^d

where value(type) is the length of the graphic type in quarter notes (eighth = 1/2, 16th = 1/4…) and d is the number of dots. The exact fraction replaces <duration> only if they differ by less than one division, which protects against unusual notations.

Note 15 — Chords in pass 1

MusicXML marks a chord on its second and following notes with <chord/>. The first note does not know it starts a chord. When the first <chord/> note is completed, the previous event is changed to type chord, and $chord_in_process is set. When the next note without <chord/> is completed, an empty event of zero duration is inserted before it. This null event tells pass 2 where the chord ends. Only one duration is added to the date for the whole chord.

Note 16 — Fermatas in the first voice

A note or rest with a <fermata> in the first voice of the part (before any backup) gets its duration doubled. The date of the fermata and the added duration are stored in $p_fermata_date[measure][part][] and $p_fermata_duration[…][], and the total added duration of the measure is kept in $p_fermata_total_duration. The other voices are lengthened at the same dates in pass 2 (note 28), and backups are corrected by the total (note 27), so that all voices remain synchronised.

Note 17 — Pitches and ties

The note name is built from <step>, <alter> (#, ##, b, bb) and <octave>, e.g. Eb5. For unpitched percussion, <display-step> and <display-octave> are used. Double accidentals are replaced later (note 35).

<tie type="start"/> appends & to the name and <tie type="stop"/> prepends it. A note in the middle of a chain of ties gets both: &A5&. The converter does not join tied notes itself: the console does this when the item is played. This is why ties may cross bar lines and voices.

Note 18 — Durations and grace notes

The <duration> of a note is stored as an integer number of divisions (p_dur, with q_dur = 1), unless it is corrected by note 14 or 16. A grace note (<grace/>) has no duration in MusicXML and gets p_dur = 0. Its actual duration is taken from the following note in pass 2 (note 30).

Note 19 — Reading tempo

Tempo comes from three sources, depending on the option chosen by the user ($tempo_option):

  • <sound tempo="…"/>: the playback tempo, in quarter notes per minute, called descriptive in the trace. It is read unless the option is “ignore” or “score”.
  • <per-minute> inside a printed <metronome> mark, called prescriptive. It is read with the options “all”, “score” and “allbutmeasures”, and converted to quarter notes per minute according to the <beat-unit> of the mark: beat_divide() gives its length in quarter notes (eighth = 1/2, half = 2…), and each <beat-unit-dot/> multiplies it by (2d+1 − 1) / 2d. For example, “dotted quarter = 60” gives 90.
  • <words> such as “Allegro” or “Adagio”, if “Interpret tempo signs” is checked. They are looked up in the table $dynamic_sign_to_tempo.

Every value goes through the metronome mapping (note 9), and is added to the statistics and to the per-measure sum $sum_tempo_measure. Except with the option “allbutmeasures”, it also creates an event of type mm with zero duration at the current position. With “allbutmeasures”, a measure gets only the average of the tempi found in it.

Note 20 — Time signature

<beats> and <beat-type> are stored per part in $time_beats[] and $time_beat_type[]. Composite values like 3+2 are added up. They persist across measures and sections, and are only used by the option for overfull measures (note 32).

Note 21 — Dynamics

Values of <sound dynamics="…"/> and dynamic signs inside <dynamics> (with or without attributes) (converted with the table $dynamic_sign_to_volume: p = 49, mf = 75, ff = 101…) are summed for the part in the current measure. Their average becomes the velocity or volume of the measure (note 34).

Note 22 — Backup and forward

A <backup> moves the current date backwards, so the notes that follow belong to another voice. It creates an event of type back carrying the backup duration, followed by an empty seq event, and resets the date of the voice to zero. Pass 2 closes the current field at this event and opens a new one.

A <forward> moves the date forwards without sound. It creates a rest event with the flag forward, which prevents pass 2 from treating it as a grace note even when it follows notes of zero duration.

Note 23 — Breath marks

If breaths are included, the date of each <breath-mark> is stored in $breath_location[], computed from $sum_durations and the duration of the note carrying the mark. A breath found again in another voice at the same date is a duplicate and is ignored. In pass 2 a silence of the chosen breath length is inserted at that date in every voice (note 31).

Note 24 — Articulations, ornaments and pedals

These signs only set attributes of the current event:

  • <arpeggiate> → arpeggio;
  • <staccato> or <spiccato> → staccato = 1, and <staccatissimo> → 2;
  • <trill-mark> → ornament = “trill”, with the attribute trill-beats (3 by default);
  • <inverted-mordent> → “upper_mordent” and <mordent> → “lower_mordent”, with the attributes long and approach;
  • <turn> → turn, with the attribute beats (4 by default);
  • <slur type="start|stop"> → slur;
  • <pedal type="…" sign="…"> → sustain, sostenuto or soft = “start”, “stop” or “stopstart”.

Each ornament can be ignored, and made chromatic, with the options of the form.

Note 25 — Pass 2: streams

Pass 2 runs over the events of the part and writes the polymetric text into $convert_measure[$score_part]. Its central idea is the stream: consecutive notes or rests of the same duration are collected in $stream, together with their number $stream_units and their total duration $p_stream_duration/$q_stream_duration in divisions.

When an event of a different duration arrives (or a backup, a chord, or the end of the part), the stream is flushed. Its total duration is converted to beats by dividing by $divisions and simplified (note 40):

  • if the number of units equals the number of beats, the notes are written as they are: C5 D5;
  • otherwise they are enclosed with their duration: {1,Eb5 F5 G5} for a triplet of eighth notes;
  • a stream consisting of a single rest of 2 or 3 beats is written as - - or - - -.

The date reached by the voice, $p_time_field/$q_time_field, is then advanced by the stream duration. This grouping keeps the text short: a run of sixteenth notes becomes one expression instead of one ratio per note.

Notes are written into the stream by add_note(). It adds placeholders for slurs (_legato_), pedals (_sustainstart_…) and ornaments (note 36). It writes a staccato note as {1,C4 -} (half note, half silence) and a staccatissimo as {1,C4 - - -}.

Pass 2 also computes $physical_time, the duration of each voice in seconds at the current tempo, which is only used for tracing.

Note 26 — Tempo changes inside a measure

Tempo changes are only read from the first field of the measure: the first voice of the first selected part. An mm event there writes a marker ||90|| at the current position, and its date is stored in $p_date_new_tempo[], with its value in $value_new_tempo[].

All other fields must change tempo at the same dates, otherwise they would drift. In each other field, before writing an event, the converter compares the date of the field with the date of the next tempo change. A tolerance of 1/20 beat absorbs rounding errors. When the date is reached, the same ||n|| marker is inserted. If the change falls inside a rest, the rest is split: its first part is written at the old tempo, the marker is inserted, and the remaining part follows. Two identical values at the same date are reduced to one; this happens when both the printed and the playback tempo of a mark are read.

The markers become _tempo() instructions when the measure is closed (note 33).

Note 27 — End of a voice (backup event)

When pass 2 meets a back event, the pending stream is flushed, and a pending breath is added. The field is closed with a marker §n§,, where n is the index of the field. The duration reached by the field is stored in $p_field_duration[n]. The longest field so far is kept in $p_time_measure.

The next voice may not start at the beginning of the measure. Its starting date is the date reached by the closed field, minus the backup duration, plus the total fermata extension of the first voice (note 16), which the backup does not include. If this date is greater than 1/100 beat, the new field starts with a rest of that length. A negative value is an error of the score: it is reported in the trace and ignored. A smaller value is treated as a rounding error.

Note 28 — Fermatas in the other voices

In fields other than the first, when a note starts at or after the date of the next fermata (note 16), its duration is increased by the fermata extension. If a rest covers that date, the rest is lengthened instead. The index $i_fermata then moves to the next fermata of the measure.

Note 29 — Chords

The first event of type chord flushes the pending stream and opens an expression {d,, where d is the duration of the chord in beats (omitted if it is 1). Each note of the chord is followed by a comma, so it becomes a field of its own: {2,F3,A3}. The null event inserted by pass 1 (note 15), or a tempo event, closes the brace. Placeholders for slurs and pedals found in the upper notes of a chord are written before the note concerned.

Note 30 — Grace notes

Grace notes form a stream of zero duration. When the next note with a real duration arrives, the stream gets a duration taken from that note:

  • half a beat per grace note ($grace_ratio = 2), or 1/8 beat for a single grace note (ratio × 4);
  • if the following note is shorter than twice this value, the grace notes take that note's duration divided by the same ratio.

The following note is shortened by the same amount, so the total duration of the voice is unchanged.

A chord of grace notes gets the placeholder FRACTION_0 as its duration, since the duration of the next event is not yet known. When the next chord or note is written, grace_chords() replaces the placeholder with a quarter of that event's duration (1/(2 × $grace_ratio)), or less if several grace chords would take more than half of it. The event is shortened by the same amount, and the date of the field is advanced by the duration of the grace chords.

Note 31 — Breaths

When a note reaches the date of a breath mark (note 23), a silence of the breath length is inserted after it. Outside a stream, this silence is written directly as a fraction, e.g. 1/4. Inside a stream, it cannot simply be written in beats, because a stream {D, n1 … nk} gives each symbol D/k beats. The placeholder _rest is written instead. When the stream is flushed, add_breath_to_stream_duration() adds the breath length to D and replaces _rest with a silence of breath × k / D symbols, which lasts exactly the breath length. The duration of the measure is increased by the breath length. An optional tag [tag] makes breaths easy to find in the data.

Note 32 — Closing the part: duration and padding

At the end of the part's events:

  1. process_arpeggios() realises the arpeggios of the part (note 38).
  2. The last stream is flushed and the last field is closed.
  3. The duration of the part is the longest field, plus the breath length if a breath was found.
  4. If the option “Keep the length of overfull measures” is set, this duration is compared with the length given by the time signature ($time_beats × 4 / $time_beat_type beats, plus fermata and breath extensions). If the part is longer, its expression gets the length of the time signature, so the overfull voice is played faster instead of lengthening the measure. This handles scores where a voice holds more notes than its time signature allows.
  5. Double accidentals are replaced (note 35), ornaments are realised (note 36) and pedal placeholders are renamed (note 39).
  6. The part is written as {duration, field1, field2, …}.
  7. Padding: the target duration is the longest field that contains at least one note (fields of silence do not count), or the length of the time signature if the measure was compressed. Every shorter field gets a rest at its end. The rest is inserted after the marker §n§ of the field. If tempo changes of the first field fall inside this added rest, it is split as in note 26.

The markers §n§ are deleted once the measure is complete.

Note 33 — Tempo of the measure

Each part of a measure starts with the placeholder _tempo(TEMPO_THIS_MEASURE). Its value M is the last tempo read ($final_metronome). Failing that, it is the average of the tempi of the measure, or the default tempo of the section. The placeholder becomes _tempo(M/60) as a simplified fraction, or is deleted when M = 60.

The markers ||n|| inside the measure are then replaced with _tempo(n/M), relative to the tempo of the measure, and deleted when n = M. Since every measure states its tempo, any measure can be played separately with the correct tempo.

Note 34 — Dynamics, channels and parts

After the tempo, each part of each measure gets:

  • _vel(v) or _volume(v): the average of the dynamics found in this part of the measure (note 21). Without dynamics in the measure, the last value of the part is used (64 at the start). At each repetition of a section, the values are reset to those of the beginning of the section. The value is repeated in every measure for the same reason as the tempo.
  • _chan(n) if “Interpret parts as MIDI channels” is checked, with the MIDI channel of the part;
  • _part(i), _rndtime(…) and _rndvel(…) if the score has several parts and these options are set. With a single part, randomisation is written once at the start of the score.

Note 35 — Double accidentals

Bol Processor note names carry a single accidental, so fix_alterations() replaces double sharps and double flats with the enharmonic equivalent: F## → G, Ebb → D, etc. Two of them change octave: B##4 → C#5 and Cbb4 → Bb3.

Step 3 — Ornaments, arpeggios and pedals

Note 36 — Ornaments

In pass 2, add_note() wraps an ornamented note in a placeholder that carries everything needed to realise it later:

ornament(SCALE_MEASURE_DIRECTION,MODE,TURN,LONG|NOTE)

SCALE is the altered diatonic scale of the measure as pitch classes (note 37), DIRECTION is upper, lower, uppertrill or lowertrill, MODE is chromatic or empty, TURN is turn=n or empty, and LONG is the value of the long attribute. When the part of a measure is complete (note 32), process_ornamentation() parses each placeholder and replaces it with the expression returned by ornament(), using the key signature of that part.

ornament() first finds the neighbour notes: the next degree above or below in the altered diatonic scale, or a semitone with the chromatic option. Then it builds an expression that lasts exactly one symbol of the stream, the duration of the original note:

  • Mordent, short: {1/8,D5 E5} {7/8,D5}; long: {1/4,E5 D5 E5} {3/4,D5} (upper mordent on D5, with a lower neighbour for a lower mordent).
  • Trill: {1,N U N U …} with trill-beats pairs, where U is the upper neighbour. It starts on the upper neighbour (U N U N …) if the note starts a tie, or if the previous note has the same pitch. add_note() checks the latter with the list $last_notes.
  • Turn: {1,N{d,U N L …} N}, where L is the lower neighbour. Only <turn> is read, so turns always start from above. The group has d = 1 unit for a short turn, followed by N_ (a note prolonged over 2 units), or d = 2 units for a long turn, followed by N. With more than 4 beats, the group gets extra alternating notes and a longer d.

Tie signs on the ornamented note are kept on the main note. The start of a tie (N&) goes on the last note of the expression, which is always the main note. The end of a tie (&N) goes on the first note if it is the main note: the short mordent, the turn, and the trill, which then starts on the main note so that it is not repeated. A long mordent starts on the auxiliary note, so it cannot continue a tie. Slur and pedal placeholders attached to the note are moved before the expression.

Note 37 — Scales for neighbour notes

diatonic_scale($fifths) returns the seven pitch classes of the key. It starts from C major (0, 2, 4, 5, 7, 9, 11). For a positive number of fifths it raises F, then every fourth degree (F, C, G, D…). For a negative number it lowers B, then every third degree (B, E, A, D…).

During pass 2, adjust_scale() records accidentals that restore a natural degree inside the measure. For example, after a B natural in F major, the neighbour of A or C becomes B instead of B♭. A copy of this altered scale is stored in each ornament placeholder, because realisation happens after the whole part of the measure has been written. When choosing sharp or flat names, the sign of $fifths decides: sharps for sharp keys, flats for flat keys.

Note 38 — Arpeggios

An arpeggiated chord is preceded by the placeholder arpeggio(m) in pass 2. process_arpeggios() splits the chord {d, A, B, C} into two consecutive expressions:

{d1, A& B& C&} {d2, &A, &B, &C}

The notes are first played one after the other, each one tied to its copy in the chord that follows, so that it keeps sounding until the end. The spread d1 is 1/20 beat per note, limited to half the duration of the chord, and d2 = d − d1. Notes that were already tied keep their ties, and placeholders for slurs and pedals are moved to the first expression.

Note 39 — Pedals

When the part of a measure is complete, rename_pedals() renames the pedal placeholders written by add_note() as _switch_on_sustain_part(i), _switch_off_sostenuto_part(i), and so on, where i is the position of the part in the part list. The scan of data.php uses the same position to record which parts contain pedal marks. In data.php, these become _switchon(controller,channel) and _switchoff(controller,channel). The controller is the one chosen by the user for each part (64 by default for sustain), or 66 for sostenuto and 67 for soft. The channel is the MIDI channel chosen in the form.

Arithmetic

Note 40 — Exact fractions

All dates and durations are pairs of integers p/q, counted in divisions. Floating-point numbers would accumulate errors over hundreds of notes, and the voices of a measure would no longer have exactly the same length.

  • add($p1,$q1,$p2,$q2) returns the sum as a reduced fraction. Subtraction is done by adding -$p2, and comparisons by testing the sign of p × q of a difference.
  • gcd() uses fmod() to avoid integer overflow with large terms, so it returns a float. Cast it with intval() when an integer is required.
  • simplify($fraction,$max_term) reduces a fraction written as text and returns its text form, its numerator and its denominator. If a term of the reduced fraction exceeds $max_term_in_fraction (32768), the fraction is scaled down proportionally and rounded, which keeps the text short at the cost of a tiny approximation. If a term would be rounded to 0, the exact reduced fraction is returned instead.

Limitations

  • The file must be uncompressed MusicXML in partwise format, with one element per line.
  • Divisions and key signature are read once per part (note 3).
  • Volta brackets are not interpreted (note 6).
  • Tempo changes are taken from the first voice of the first selected part only (note 26).
  • Hidden notes are only removed in measures that contain an ornament realised by the converter (note 7).

Debugging an import

The form offers several traces, displayed above the options after conversion: “Trace all corrections of this score” (backups, added rests, fermatas, breaths), “Trace tempo variations”, “Trace measures n to m” (restricted to a range of measures), and “Trace ornamentations and arpeggios”. In _musicxml.php, setting $super_trace or $trace_breath to TRUE gives more detail about streams and breaths. The button “PREVIEW MusicXML file” shows a simplified view of the source, optionally filtered to show only the measures containing a given sign.

When an imported piece sounds wrong, the most frequent causes are a voice of the wrong length, which is then stretched; a backup inconsistent with the durations of the previous voice (reported in the trace); and very long ratios caused by odd durations, which often indicate hidden playback notes (note 7) or rounded tuplets (note 14). The console reports tied notes it could not join in the messages “Missed tied note”.

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

Carrying over controls

 

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 in Csound they set arguments of the score: see Csound check. Additional Csound parameters, declared in a Csound resource file, are set in the same way with _value(): see Csound objects.

A control applies to what follows it in its own expression. Until recently (version 3.6.0), an expression without controls of its own reverted to the default values: volume 90, panoramic 64 (centre), no modulation, no pressure, no pitchbend. This was impractical for scores made of successive polymetric expressions, such as scores imported from MusicXML, in which each measure is a polymetric expression whose fields are the parts of the score. Setting the stereo position of a string quartet required a _pan() control for each part in every measure.

Now, a fixed value of a control is carried over to the following expressions that do not set it. The Bol Processor decides which expressions receive it according to the part, the instrument or the MIDI channel to which it is attached. This page explains the rules.

The examples are found in the data project "‑da.checkCarryOver" (folder "ctests"), in which each item states the values it should produce. They are shown here with the Csound scores they produce, using the Csound resource "‑cs.Beethoven-fugue-b-flat-major" designed for a string quartet. In these scores:

  • arguments 5 and 6 (red) are the start and end volume (default 90);
  • arguments 15 and 16 (blue) are the start and end panoramic (default 64);
  • part 1 is played by instrument 1 (violin), part 2 by instrument 4 (second violin); notes without a part are played by instrument 1.

MIDI output follows the same rules, since the values of the controls are the same. In MIDI, a controller message is sent on the channel of a note whenever its value differs from the previous one on this channel.

Values carried over

In a sequence, a value set by a control applies to the following notes, even if they are sent to another MIDI channel. Here, all three notes are played at volume 20:

_volume(20) C4 _chan(2) D4 _chan(3) E4

The same is now true when the notes are in separate expressions:

{_volume(20) C4} {_chan(2) D4} {_chan(3) E4}

i1 0.000 1.000 8.00 20.000 20.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 20.000 20.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 2.000 1.000 8.04 20.000 20.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

Before this change, D4 and E4 were played at the default volume 90.

To which part, instrument or channel does a value belong?

A value is attached to:

  1. the instrument if _ins() has been specified;
  2. otherwise, the part if _part() has been specified;
  3. otherwise, the MIDI channel if _chan() has been specified;
  4. otherwise, the current instrument: the one guessed by _value() for an additional parameter (see below), or instrument 1.

An item starts with the implicit values _ins(1) _part(1) _chan(1). A note that does not receive the value from its own expression takes the value attached to its instrument, its part or its channel, including implicit ones. In the previous example, the volume 20 was attached to the implicit instrument 1, which is also that of D4 and E4.

Values attached to parts remain separate, even if the parts are sent to the same MIDI channel:

{_part(1) _volume(30) C4, _part(2) _volume(110) E4} {_part(1) D4, _part(2) F4}

i1 0.000 1.000 8.00 30.000 30.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i4 0.000 1.000 8.04 110.000 110.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4
i1 1.000 1.000 8.02 30.000 30.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i4 1.000 1.000 8.05 110.000 110.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; F4

This is what makes it possible to set the stereo position of each part once and for all, in the first measure of a score. In the third measure, a new value changes the position of part 2:

{_part(1) _pan(23) C4 D4, _part(2) _pan(48) E4 F4} {_part(1) G4 A4, _part(2) B4 C5} {_part(1) D5 E5, _part(2) _pan(100) F5 G5}

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; C4
i4 0.000 1.000 8.04 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; E4
i1 1.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; D4
i4 1.000 1.000 8.05 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; F4
i1 2.000 1.000 8.07 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; G4
i4 2.000 1.000 8.11 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; B4
i1 3.000 1.000 8.09 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; A4
i4 3.000 1.000 9.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; C5
i1 4.000 1.000 9.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; D5
i4 4.000 1.000 9.05 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 100.000 100.000 0.000 ; F5
i1 5.000 1.000 9.04 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; E5
i4 5.000 1.000 9.07 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 100.000 100.000 0.000 ; G5

A value set after _ins() belongs to the instrument, so it is not affected by _part() or _chan() instructions that follow:

{_ins(3) _volume(50) C4} {_ins(3) _part(2) D4 _chan(5) E4}

i3 0.000 1.000 8.00 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i3 1.000 1.000 8.02 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i3 2.000 1.000 8.04 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

Conversely, it does not apply to another instrument, even in the same part. Here D4 gets the default volume:

{_ins(3) _part(2) _volume(50) C4} {_ins(4) _part(2) D4}

i3 0.000 1.000 8.00 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i4 1.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4

An explicit _chan(1) is not the same as the implicit channel 1. Here, the volume 50 belongs to channel 1, so D4 on channel 2 does not receive it, whereas it would without _chan(1):

{_chan(1) _volume(50) C4} {_chan(2) D4}

i1 0.000 1.000 8.00 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4

A Csound resource file may assign an instrument to a MIDI channel. If _ins() was given outside a polymetric expression, a _chan() inside this expression that selects such a channel overrides it: the following notes are played by the instrument of the channel, and the values set after _chan() belong to the channel. An _ins() given in the same field as _chan(), as in the previous examples, keeps its priority.

In the following example, item #26 from "‑da.tryCsound", the Csound resource "‑cs.tryCsound" assigns instrument 3 (harpsichord) to channel 2. E4 and F4 are played by instrument 3, and F4 receives the volume 50 attached to channel 2. G4 is played again by instrument 1, with the volume 30 attached to it. (The volume is on arguments 5 and 6 of instrument 1, and on arguments 7 and 8 of instrument 3.)

_ins(1) {_volume(30) C4} {_chan(2) _volume(50) E4} {_chan(2) F4} {G4}

i1 0.000 1.000 8.00 30.000 30.000 0.000 0.000 0.000 0.000 ; C4
i3 1.000 1.000 329.628 8192.000 8192.000 50.000 50.000 0.000 0.000 0.000 0.000 0.000 ; E4
i3 2.000 1.000 349.228 8192.000 8192.000 50.000 50.000 0.000 0.000 0.000 0.000 0.000 ; F4
i1 3.000 1.000 8.07 30.000 30.000 0.000 0.000 0.000 0.000 ; G4

The most recent value

When several values are attached to the instrument, the part and the channel of a note, the most recent one wins. If they were set at the same time, as in the fields of a polymetric expression, the order of priority is: instrument specified by _ins(), part, channel, and finally the implicit instrument.

In the following example, the volumes 80 and 30 are both set at date 0. The volume 80 belongs to the implicit instrument 1, the volume 30 belongs to part 2. Therefore D4, in part 2, gets 30, while F4, which has no part, gets 80:

{_volume(80) C4, _part(2) _volume(30) E4} {_part(2) D4} {F4}

i1 0.000 1.000 8.00 80.000 80.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i4 0.000 1.000 8.04 30.000 30.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4
i4 1.000 1.000 8.02 30.000 30.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 2.000 1.000 8.05 80.000 80.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; F4

Variations are not carried over

Only fixed values are carried over. A value belonging to a continuous variation (_volumecont, _pitchcont, _cont(), etc.) or a stepwise variation (_volumestep, etc.) describes a movement within its own expression. It erases the remembered value, and the following expressions get the default value:

{_volume(80) C4} {_volumecont _volume(20) D4 E4 _volume(100)} {F4}

i1 0.000 1.000 8.00 80.000 80.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 20.000 60.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 2.000 1.000 8.04 60.000 100.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4
i1 3.000 1.000 8.05 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; F4

This is important for pitchbend: the end of a glissando such as _pitchcont _pitchbend(0) C4 D4 _pitchbend(100) should not detune the notes that follow.

The value erased is the one attached to the part, instrument or channel of the variation. A value attached elsewhere may then apply again. Below, the variation of part 2 erases the value of part 2, so E4 receives the volume 80 attached to the implicit instrument 1:

{_volume(80) C4} {_part(2) _volumecont _volume(20) D4 _volume(100)} {_part(2) E4}

i1 0.000 1.000 8.00 80.000 80.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i4 1.000 1.000 8.02 20.000 100.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i4 2.000 1.000 8.04 80.000 80.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

Only for later expressions

A value only applies to expressions starting after the date at which it is set. Fields of the same polymetric expression starting at the same time do not share their values, otherwise the result would depend on the order in which the fields are written. Here, D4 gets the default volume and E4 gets 20:

{_volume(20) C4, D4} {E4}

i1 0.000 1.000 8.00 20.000 20.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 0.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 1.000 1.000 8.04 20.000 20.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

As a consequence, a value written at the very end of an expression does not reach the next one, since its date is the start date of the next expression. Here, D4 is played at volume 90:

{C4 _volume(50)} {D4}

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4

Values are carried over to expressions that do not set them. In the following example, E4 does not belong to an expression of its own: it follows C4 in the main sequence, which has already received the default value. So E4 is played at volume 90:

C4 {_volume(50) D4} E4

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 2.000 1.000 8.04 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

Writing E4 in an expression of its own, it receives the volume 50:

{C4} {_volume(50) D4} {E4}

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; C4
i1 1.000 1.000 8.02 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; D4
i1 2.000 1.000 8.04 50.000 50.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 64.000 64.000 0.000 ; E4

Chunks

Values are also carried over from one line of a data item to the next, since each line is played as a chunk. This is the case when a long item is played with the "PLAY safe" button, which splits it into chunks to save memory. In the following item, D4 and F4 keep the stereo positions of their parts:

{_part(1) _pan(23) C4, _part(2) _pan(48) E4}
{_part(1) D4, _part(2) F4}

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; C4
i4 0.000 1.000 8.04 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; E4
i1 1.000 1.000 8.02 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 23.000 23.000 0.000 ; D4
i4 1.000 1.000 8.05 90.000 90.000 0.000 0.000 0.000 0.000 64.000 0.000 0.000 0.000 48.000 48.000 0.000 ; F4

Items produced by a grammar do not share their values: each item starts with the default values.

Additional parameters

The same rules apply to additional Csound parameters set by _value(). Examples are found in the section "Carrying over additional parameters" of "‑da.tryCsoundObjects", using the Csound resource "‑cs.tryCsoundObjects" in which instrument 6 has a parameter "blah" on arguments 15 and 16 (default 231.5).

A _value() instruction guesses the instrument to which its parameter belongs, here _ins(6). This guessed instrument does not count as specified, so the values of the parts below remain separate:

{_part(1) _value(blah,10) C4, _part(2) _value(blah,20) E4} {_part(1) _ins(6) D4, _part(2) _ins(6) F4}

i6 0.000 1.000 8.00 0.000 0.000 90.000 90.000 0.000 0.000 0.000 1.000 1.000 0.000 10.000 10.000 0.000 ; C4
i6 0.000 1.000 8.04 0.000 0.000 90.000 90.000 0.000 0.000 0.000 1.000 1.000 0.000 20.000 20.000 0.000 ; E4
i6 1.000 1.000 8.02 0.000 0.000 90.000 90.000 0.000 0.000 0.000 1.000 1.000 0.000 10.000 10.000 0.000 ; D4
i6 1.000 1.000 8.05 0.000 0.000 90.000 90.000 0.000 0.000 0.000 1.000 1.000 0.000 20.000 20.000 0.000 ; F4

A carried value combines with the values found in the Csound scores of sound-objects, according to the combination mode of the parameter (additive or multiplicative), just like a value set explicitly.

These rules were designed with the score of Beethoven's Grosse Fugue (opus 133) for string quartet, imported from MusicXML: the stereo positions of the four parts are set by _pan() controls in the first measure only. In unusual situations, the result might not be the one you expect. Please let us know!

Beethoven's Fugue in B flat major interpreted by the Bol Processor + Csound, with Sauveur temperament
👉 Listen in stereo!

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 and Csound drivers.
A new output format (event lists) makes it possible to connect the Bol Processor to the largest diversity of sound software devices.

🎶 The relocation or truncation of sound-objects, constraints on continuity, and the use of broken tempo (organum), bear similarities to the actions of human musicians during a performance. Virtuose performers need to break the rigidity of the beats in order to fully express the musicality of specific events.

All examples discussed here can be found in the Data project '-da.tryMiscObjects'. The time-setting of sound-objects uses an algorithm that has been documented in detail in previous publications.

Simple notes and sound-objects

In the Bol Processor, time-objects that produce (musical) sounds are of two types:

  • Simple notes are expressed in English, Italian-French or Indian conventional notation as a note name followed by an octave number. For example, C4 in English notation designates the note C in the fourth octave, which is usually the #60 key in the middle of a piano keyboard. C4 is equivalent to do3 in Italian-French notation and sa4 in Indian notation.
  • Sound-objects, which will be discussed here, are 'packages' of instructions (in MIDI or/and Csound formats) able to describe a set of instructions that may be likened to a 'musical gesture'.

The first version of the Bol Processor (BP1), released in 1980, dealt exclusively with sound objects representing the 'gestures' of Indian drummers and dancers. Within the current technical limitations, it produced and analysed musical items in text format, which the mussicologist could read or play on a drum. Read for example Analysis of tabla compositions.

Later, when the MIDI and Csound formats became available on small computers, handling simple notes and sound objects was introduced to expand the scope.

Editing sound-objects on BP3

Throughout this tutorial, we will become familiar with three types of sound object from a technological perspective:

  • MIDI objects produced by MIDI code
  • Csound objects produced by converting MIDI code to a Csound score
  • Pure Csound objects defined in Csound scores

Open the '-da.tryMiscObjects' project, which is distributed in the 'ctests' folder. A line of buttons at the bottom of the edit window gives access to the connected files. For example, since '-so.tryObjects' is written at the top of the project, a button with the same name is visible. Clicking this button displays the full set of sound objects used by this project:

👉 This tab must never be closed if sound objects are to be modified or created. A javascript scheduler checks for modifications to the sound objects every 30 seconds, and automatically saves the updated '-so.tryObjects' file. A message on top of the '-so.tryObjects' page confirms it:

If you are in a hurry, you can of course click the SAVE '-so.tryObjects' button.

Every sound-object is of the MIDI or Csound type, or both.

Click any name of sound-object, e.g. 'cycle1', to open the sound-object editor in a new tab:

This sound-object contains both MIDI and Csound code, producing identical sequences of events, as the Csound score at the bottom of the page was automatically generated from the MIDI content.

You can modify the Csound score, save it, then save the prototype and wait for less than 30 seconds for it to be updated in the '-so.tryObjects' file.

The advantage of using Csound scores for sound-objects is that they can represent much more complex instructions than MIDI messages, as they can control any number of parameters (arguments) in a Csound instrument. The instrument number 'x' or label can be set using the _ins(x) command in the Bol Processor score. Alternatively, it can be made specific to this sound object by entering the instrument number in the 'Force to instrument' field.

The MIDI sequence can be played by clicking the PLAY button, and it can be exported as a MIDI file. Conversely, a new MIDI sequence can be uploaded to the sound-object. This sequence, for example, was created using the MIDI file output format in the Bol Processor.

An image of the sound-object is available at the bottom of its page:

This image highlights a property of 'cycle1': as its name suggests, it is cyclic. This means that, if an extension is required but the 'Never rescale' option at the top of the page prevents this, it will fill the time interval with self-replications of its MIDI or Csound sequence. Replications are set to start at 34 % of its duration. This parameter can also be specified in milliseconds. Beware that if you enter a negative value or a value larger than the sound-object's duration, it will be set to 0. The same restrictions apply to parameters such as CONTINUITY, COVER, and TRUNCATE.

Creating a new sound-object

Let us create a sound-object labelled 'oscar' using a phrase of Oscar Peterson in the imported MusicXML score '-da.Watch_What_Happens_by_Oscar_Peterson'.

First click the EXPLODE button to split measures. Find one that you feel eligible as a sound-object. We selected measure #6:

This is the Bol Processor score of this measure:

{_vel(64) _chan(1){4, {{3,D5&}{1,&D5 G5 Bb5 D6 C6 Bb5}, {3/2,- F4 Gb4}{1/2,A4 Gb4}{2,G4}}}, _vel(64) _chan(2){4,{{3/2,- F3 Gb3}{1/2,A3 Gb3}G3&{1,&G3 G3 Bb3 D4 C4 Bb3}, 1/2{3/2,Bb2}--}}}

To export this fragment as a MIDI file, first set the Fade-out time to zero in the settings, otherwise it will end with 2 seconds of silence. Then select the MIDI file output format and click 'PLAY' near the 6th item. Click 'download' to get a file named 'Watch_What_Happens_by_Oscar_Peterson.mid' which contains only the chosen measure.

Then go back to the '-so.tryObjects' page and create an object called 'oscar'. Add 'oscar' to the '-al.tryObjects' alphabet which can be accessed via the link near the bottom of the '-da.tryMiscObjects' page. As 'oscar' belongs to the terminal alphabet, it should start with a lowercase character. However, you can bypass this rule by typing it between single quotation marks.

Open the 'oscar' tab and click the choose file button near 'Create or replace MIDI codes loading a MIDI file'. This will allow you to upload the MIDI file. Then click 'SAVE THIS PROTOTYPE'.

The duration of this sound-object is now set to 1820 ms, which is 1.82 beats because its time reference Tref is set to 1000 ms (by default). All default properties are fit for this demo, we'll change a few of them later.

Don't forget to wait for at least 30 seconds so that the new object is saved along with the '-so.tryObjects' file. The return to '-da.tryMiscObjects', type 'oscar' in the edit field and play it in real-time MIDI or MIDI file. You will get the following pianoroll and sound:

Now, you can also create the equivalent Csound score of this object by clicking the 'CREATE Csound CODE from MIDI codes' button. Wait a few seconds for the processing to complete. You will get:

t 0.000 60
i1 0.227 0.228 8.05 90.000 90.000 0.000 0.000 0.000 0.000 ; F4
i1 0.227 0.228 7.05 90.000 90.000 0.000 0.000 0.000 0.000 ; F3
i1 0.455 0.227 8.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#4
i1 0.455 0.227 7.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#3
i1 0.682 0.114 8.09 90.000 90.000 0.000 0.000 0.000 0.000 ; A4
i1 0.682 0.114 7.09 90.000 90.000 0.000 0.000 0.000 0.000 ; A3
i1 0.796 0.114 8.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#4
i1 0.796 0.114 7.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#3
i1 0.227 0.683 6.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#2
i1 0.000 1.365 9.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D5
i1 0.910 0.455 7.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G3
i1 1.441 0.076 9.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G5
i1 1.441 0.076 7.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G3
i1 1.517 0.075 9.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#5
i1 1.517 0.075 7.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#3
i1 1.592 0.076 10.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D6
i1 1.592 0.076 8.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D4
i1 1.668 0.076 10.00 90.000 90.000 0.000 0.000 0.000 0.000 ; C6
i1 1.668 0.076 8.00 90.000 90.000 0.000 0.000 0.000 0.000 ; C4
i1 1.744 0.076 9.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#5
i1 0.910 0.910 8.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G4
i1 1.744 0.076 7.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#3
;

Click the 'SAVE THIS CODE' button, then 'SAVE THIS PROTOTYPE'.

The Csound code is only used when the output format is Csound. Real-time MIDI and MIDI files use the MIDI codes of sound-objects. For this reason, if a sound-object contains only Csound code, it won't produce any sound in MIDI.

Csound

An introduction to using Csound with the Bol Processor is found on the Csound checkup page.

Select the Csound score output format and play 'oscar'. You get the following:

No MIDI output, as the Bol Processor produced a Csound score output which the Csound console converted to a sound file. The notes are drawn in green on the pianoroll instead of brown, indicating that Csound is being used instead of MIDI.

The MIDI code stored in 'oscar' was not used. Instead, the Csound score was used.

If the sound-object contains MIDI code and no Csound score, using it with the Csound output option will convert MIDI to Csound for this particular task.

What happens if a sound-object contains Csound score and no MIDI code? Try it by duplicating 'oscar' to 'oscar-purecsound' and click the 'SUPPRESS all MIDI codes' button on the 'oscar-purecsound' page. Don't forget to add 'oscar-purecsound' to the '-al.tryObjects' alphabet!

Now, playing 'oscar-purecsound' will produce the same output as 'oscar' with the 'Csound score output' option selected. However, you will not hear any sound if you play 'oscar-purecsound' with the real-time MIDI or MIDI file output option selected.

The Bol Processor can convert streams of MIDI codes into Csound scores. However, it cannot perform the reverse conversion for a simple reason: Csound uses events that are too complex for straightforward conversion to MIDI.

On this page, we use the minimum set of arguments in Csound scores (10) which makes them eligible for a sound rendering by the instruments described in the Csound resource '-cs.tryTunings'. A more sophisticated use is explained on the Csound objects page. A practical example using 13 arguments is proposed on the Sarasvati Vina grammar project.

MIDI channels and Csound instruments

Looking back at the Bol Processor score used to create 'oscar' reveals that it was calling both MIDI channels 1 and 2:

{_vel(64) _chan(1){4,{{3,D5&}{1,&D5 G5 Bb5 D6 C6 Bb5},{3/2,- F4 Gb4}{1/2,A4 Gb4}{2,G4}}},_vel(64) _chan(2){4,{{3/2,- F3 Gb3}{1/2,A3 Gb3}G3&{1,&G3 G3 Bb3 D4 C4 Bb3}, 1/2{3/2,Bb2}--}}}

This probably went unnoticed when the sound object was played on a MIDI device set to mix all 16 channels by default. However, MIDI channels can be used to redirect MIDI event streams to different devices. The _part() instruction also does this on the Bol Processor. Anyway, we need options for dealing with channels contained in a sound-object's MIDI code:

The 'Do not change…' option is declared as follows in 'tryObjects.json' (created when the output option is Event list):

"Default MIDI channel": {
"key": "DefaultChannel",
"value": "LOCAL_CH",
"unit": "enum"
},

MIDI channels are preserved as found in the sound object.

If the 'Force events to the current MIDI channel' option is selected, the MIDI channel will match the context of the event. The JSON declaration is:

"Default MIDI channel": {
"key": "DefaultChannel",
"value": "GLOBAL_CH",
"unit": "enum"
},

If the 'Force events to MIDI channel #' option is selected, the specified channel number is used. For instance, with a channel number of 6:

"Default MIDI channel": {
"key": "DefaultChannel",
"value": 6
},

The same process applies to Csound instruments. These can be specified using the _inst() command in the Bol Processor score, but instruments can also be set in each sound object:

Here, for instance, instruments specified in the Csound score will be used. This is declared as follows in 'tryObjects.json':

Csound instrument mode": {
"key": "CsoundInstrumentMode",
"value": "LOCAL_CS",
"unit": "enum"
}

If the option 'Force to instrument used in context' is selected, it is declared as follows:

Csound instrument mode": {
"key": "CsoundInstrumentMode",
"value": "GLOBAL_CS",
"unit": "enum"
}

If an instrument is specified (and used for all events), it is declared as follows:

"Csound instrument #": {
"key": "CsoundInstr",
"value": 3
}

In the produced Csound score, instrument numbers appear in the first parameter. For instance, this line

i3 0.000 1.000 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4

sends a note 'C4' to a Csound instrument #3. This will work on three conditions:

  1. A Csound instrument file (such as '-cs.tryTunings') has been declared on top of the project;
  2. It contains an instrument #3;
  3. The arguments of instrument #3 match parameters found in the line.

Try for instance playing the same object with three different instruments:

_ins(1) oscar-purecsound -- _ins(2) oscar-purecsound -- _ins(3) oscar-purecsound

👉 Instrument #3 cannot play short notes. However, these are present in the output score, as shown below:

t 0.000 60
i1 0.000 1.365 9.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D5
i1 0.227 0.228 8.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F4
i1 0.227 0.228 7.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F3
i1 0.227 0.683 6.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#2
i1 0.455 0.227 8.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#4
i1 0.455 0.227 7.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#3
i1 0.682 0.114 8.09 90.000 90.000 0.000 0.024 0.024 0.000 ; A4
i1 0.682 0.114 7.09 90.000 90.000 0.000 0.024 0.024 0.000 ; A3
i1 0.796 0.114 8.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#4
i1 0.796 0.114 7.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#3
i1 0.910 0.455 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 0.910 0.910 8.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G4
i1 1.441 0.076 9.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G5
i1 1.441 0.076 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 1.517 0.075 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 1.517 0.075 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i1 1.592 0.076 10.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D6
i1 1.592 0.076 8.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D4
i1 1.668 0.076 10.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C6
i1 1.668 0.076 8.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C4
i1 1.744 0.076 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 1.744 0.076 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i2 3.000 1.365 9.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D5
i2 3.227 0.228 8.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F4
i2 3.227 0.228 7.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F3
i2 3.227 0.683 6.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#2
i2 3.455 0.227 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i2 3.455 0.227 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i2 3.682 0.114 8.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A4
i2 3.682 0.114 7.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A3
i2 3.796 0.114 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i2 3.796 0.114 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i2 3.910 0.455 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i2 3.910 0.910 8.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G4
i2 4.441 0.076 9.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G5
i2 4.441 0.076 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i2 4.517 0.075 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i2 4.517 0.075 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i2 4.592 0.076 10.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D6
i2 4.592 0.076 8.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D4
i2 4.668 0.076 10.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C6
i2 4.668 0.076 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4
i2 4.744 0.076 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i2 4.744 0.076 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i3 6.000 1.365 9.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D5
i3 6.227 0.228 8.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F4
i3 6.227 0.228 7.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F3
i3 6.227 0.683 6.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#2
i3 6.455 0.227 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i3 6.455 0.227 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i3 6.682 0.114 8.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A4
i3 6.682 0.114 7.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A3
i3 6.796 0.114 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i3 6.796 0.114 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i3 6.910 0.455 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i3 6.910 0.910 8.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G4
i3 7.441 0.076 9.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G5
i3 7.441 0.076 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i3 7.517 0.075 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i3 7.517 0.075 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i3 7.592 0.076 10.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D6
i3 7.592 0.076 8.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D4
i3 7.668 0.076 10.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C6
i3 7.668 0.076 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4
i3 7.744 0.076 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i3 7.744 0.076 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
s

A Csound sound-object can also use several instruments specified on eaach line of its Csound score. Duplicate 'oscar-purecsound' to 'oscar-2instruments', select the 'Do not change instrument', then modify the Csound score as follows:

i1 0.227 0.228 8.05 90.000 90.000 0.000 0.000 0.000 0.000 ; F4
i1 0.227 0.228 7.05 90.000 90.000 0.000 0.000 0.000 0.000 ; F3
i3 0.455 0.227 8.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#4
i3 0.455 0.227 7.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#3
i3 0.682 0.114 8.09 90.000 90.000 0.000 0.000 0.000 0.000 ; A4
i1 0.682 0.114 7.09 90.000 90.000 0.000 0.000 0.000 0.000 ; A3
i1 0.796 0.114 8.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#4
i1 0.796 0.114 7.06 90.000 90.000 0.000 0.000 0.000 0.000 ; F#3
i1 0.227 0.683 6.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#2
i3 0.000 1.365 9.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D5
i1 0.910 0.455 7.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G3
i1 1.441 0.076 9.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G5
i1 1.441 0.076 7.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G3
i1 1.517 0.075 9.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#5
i1 1.517 0.075 7.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#3
i1 1.592 0.076 10.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D6
i1 1.592 0.076 8.02 90.000 90.000 0.000 0.000 0.000 0.000 ; D4
i1 1.668 0.076 10.00 90.000 90.000 0.000 0.000 0.000 0.000 ; C6
i1 1.668 0.076 8.00 90.000 90.000 0.000 0.000 0.000 0.000 ; C4
i1 1.744 0.076 9.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#5
i1 0.910 0.910 8.07 90.000 90.000 0.000 0.000 0.000 0.000 ; G4
i1 1.744 0.076 7.10 90.000 90.000 0.000 0.000 0.000 0.000 ; A#3

Notes F#4, F#3 A4 and D5 will be played with instrument #3, and other notes with instrument #1. Save this score, save the 'oscar-2instruments', click SAVE on the -'so.tryObjects' page, add 'oscar-2instruments' to the '-al.tryObjects' alphabet, and play:

oscar-2instruments

Isn't it beautiful? 😀 

In this demo, we used instruments #1, #2 and #3 from the Csound instrument file named '-cs.tryTunings' because they each have 10 arguments that match the 10 parameters contained in the Csound scores. More complex instruments use more parameters.

This is still a small part of the sophistication of Csound, as Csound scores can handle an infinity of instruments with their specific parameters (example). You only need to design them…

Event list

Sound-objects are listed in event lists along with the parameters required for their instantiation. Indeed, the exported JSON file, e.g. 'tryObjects.json', is also used to this effect.

For example, the performance of

_ins(3) C4 - oscar-2instruments

produces an event list starting like this:

Here, the Csound instrument column displays instrument 3 for the 'C4' note. However, it states that 'oscar-2instruments' should use its own internal instrument assignments. These will be find in the Csound score stored in 'tryObjects.json'.

Duration of a sound-object

Type and play:

oscar - _tempo(1/3) oscar

The first instance of 'oscar' will play at the same speed as the captured fragment. The second instance will play at a third of the speed. This is possible because the property 'OK rescale' is selected. If you don't want to change the speed, regardless of the tempo of the performance, select 'Never rescale'.

When 'OK rescale' is selected, you can still prohibit the expansion or contraction of the duration, owing to the 'Expand' and 'Compress' options. Try to play the preceding example after unchecking 'Expand' or 'Compress', ot selecting 'Never rescale'.

A finer control of durations is possible. Select 'Dilation ratio range from' and set acceptable variations in range 0.5 to 2. Then play:

oscar - _tempo(4) oscar ---- _tempo(1/3) oscar

Speeds 4 and 1/3 won't be accepted and will be limited to 2 and 1/2:

Cover property

Now try this:

_tempo(0.5) oscar _tempo(1) oscar

Oops!

The two occurrences overlap because the second one starts on the second beat (2.00 seconds). The small red triangle at the start of the object indicates its pivot, which we will discuss later. Its shape indicates that the object is relocatable. So, how can we make the second occurrence play after the first has finished?

The solution is to set the 'COVER END' property to 'Never cover':

The same can be achieved by setting the 'COVER BEGINNING' property to 'Never cover'.

Tied sound-objects

The concatenation sign '&' used to tie notes together in articulations (read tied notes) also applies to all kinds of sound-objects. For example:

oscar& C4 &oscar

The symbolic duration of 'oscar' is extended to 2 beats, plus one beat in the middle to accommodate 'C4'. Given that the physical duration of its prototype is 1820 ms, its total duration is 3640 ms.

Below, the silent (undeclared) sound-object 'h' is used in a tie:

_tempo(2) C4 h& D4 &h E4

Pre-roll and post-roll

Note that the second occurrence in the preceding example moved exactly to the end of the first. Perhaps we need to set a safe silence of, say, 300 ms after each occurrence of 'oscar'. This can be achieved by setting the post-roll to 300 ms. Post-roll is the additional time given to a time object to finish its effect:

A similar effect can be achieved by setting a negative pre-roll, which introduces a silence at the beginning of the object. Two buttons at the bottom of the 'oscar' page make it easier to understand the concept of 'pre-roll' and 'post-roll' in terms of silences:

The pre-roll and post-roll of a sound-object can be positive or negative and are intended to frame a time interval outside the limits set by the object's first and last events. A positive post-roll means that there are 'things happening' at a given delay after the last event. A positive pre-roll indicates that 'things will happen' after a given delay following the first event. If the object has a 'Non-cover' property, the new limits will be used to calculate its location.

These delays are expressed in physical time (milliseconds), as it would make no sense for them to differ if the sound-object were played at a different speed.

Smooth time, smooth sound-object

Play the following on striated time (the default setting on '-da.trMiscObjects'):

oscar - _tempo(4/3) oscar - _tempo(2) oscar

The open the settings, uncheck the 'Striated time' option, save the settings, and play the same in smooth time.

The two results are shown below:

In striated time (top image), the pivot of each sound-object is set on a time streak (blue vertical line), and the time streaks are arranged according to the rhythmic structure.

In smooth time (bottom image), sound-objects and silences are located on the sole basis of their durations. For example, the first silence lasts for 1 second (the default setting), whereas the second silence, at tempo 4/3, lasts for 0.75 seconds.

A typical example of using smooth time is the arrangement of time patterns (empty time-objects) as shown in '-gr.tryTimePatterns' (read more):

{10,t1 t2,{t1 t3 t4,C4 D4 E4 F4 - A4}{t3 t1,B4 C5 _ E5}}

A smooth time-object is one whose Tref parameter is set to 0 ms. By default, this value is 1000 ms. This will be explained and demonstrated in future…

Silent sound-object

A silent sound-object is one in which both the MIDI and Csound contents are empty. It may be called a time-object since it does not deal with sound in its raw form. Since it does not deal with sound in its raw form, it may be called a time-object. However, once it is displayed in an event list, it may be used by other devices to produce any sequence of events.

Silent sound-objects can be created in three ways:

  1. A left-over variable
  2. A terminal symbol unrelated to a sound-object description
  3. A sound-object declared with empty MIDI and Csound contents

Check the three types in this example:

Thisvariable C4 gold gold h D4

Here, 'Thisvariable' is a left-over variable and 'h' is a terminal symbol not declared in '-so.tryObjects'. Both are played with a one-beat duration. However, 'gold' is declared in '-so.tryObjects' with a 'Tref' duration of 700 ms that cannot be rescaled, plus the 'force continuity in the beginning' property and 'relocate' properties.

The 'gold' silent sound-object can be given the same metrical and topological properties as other sound objects, creating a wide variety of situations.

Read the Silent sound-objects page for more details.

Smooth sound-object

The 'chik-smooth' silent sound-object has a 'Tref' duration of 0 ms. We call it a smooth sound-object. It 'adapts' to the current rhythmic structure by occupying 1 beat. Let us place the 'chik-smooth' pivot in the middle, allow it to be truncated and prevent its beginning from being covered. Now we play:

_tempo(2) chik C4 chik-smooth - _tempo(1) chik-smooth

The duration of 'chik-smooth' is one beat, that is 0.5 s when the tempo is 2 and 1 s when the tempo is 1.

The 'gold2' silent sound-object has a 'Tref' duration of 0 ms. We call it a smooth silent sound-object. Let us play:

_tempo(2) C4 gold gold2 gold2 D4

Here, the 'gold2' sound-object has a duration of one beat, or 0.5 seconds. The 'gold' sound-object, instead, is played at half its nominal duration, or 350 ms.

Out-time sound-object

Play:

C4 << chik >> C5

The 'chik' sound-object, normally lasting 250 ms, is played with duration zero if written between <<>>:

This is visible in the Csound score of this performance. Notes in 'chik' are {C3, F3, C4} :

i1 0.000 1.000 8.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C4
i1 1.000 0.000 7.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C3
i1 1.000 0.000 7.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F3
i1 1.000 0.000 8.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C4
i1 1.000 1.000 9.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C5
s

Pivot

The concept of pivot was first introduced in the late 1980s by the Italian composer Marco Stroppa. It is discussed in detail in Bel's paper Two algorithms for the instantiation of structures of musical objects. The pivot is a specific point in time that indicates where a sound object should be placed.

By default, the pivot is located at the beginning of its sound-object. However, it can be set at various locations: beginning (pre-roll excluded), end (post-roll excluded), middle (pre-roll and post-roll excluded), first NoteOn, last NoteOff, middle of the NoteOn/NoteOff sequence. It can also be set to start at a given distance from the beginning, either as a percentage of the total duration (excluding pre-roll and post-roll) or as a fixed number of milliseconds.

This level of sophistication is necessary given that sound-objects — or, more generally, time-objects — are intended to drive all kinds of devices, including robots.

Try for instance:

C3 F2 pivotplus

The 'pivotplus' sound-object has its pivot located at 150 % duration from its beginning. The pivot is displayed as a full red arrow, meaning that the object cannot be relocated: the time-setting algorithm will place it on a time streak according to the rhythmic structure wherever possible.

Now try:

C3 F2 pivotminus

The 'pivotminus' sound-object has its pivot located at -50 % duration from its beginning.

Now, let's take another look at the eighteenth measure of 'Watch_What_Happens_by_Oscar_Peterson.mid' by Oscar Peterson, which has been used to create the 'oscar2' sound-object:

_chan(1){{4,{{1,F5 Bb3}{1/2,G4 F4}{1/2,A4 C5 E5}Db5{1,Bb4 Ab4 -}, 2{F4,Ab4}{1,G4 F4 -}}},_chan(2){4,{{1/2,F4}{1/2,Db3 D3 Eb3}{1/2,E3 D3}{1/2,- Cb4 C4}{1,Db4 G2 Eb4}{2/3,Eb4}{1/3,Ab2},-- 2/3{1/3,F3,Cb4}{2/3,F3,Cb4}{1/3,Db2}}}}

Note that it contains notes in MIDI channels 1 and 2. The image looks like this:

The numerous red lines from 4 to 6 seconds represent a series of MIDI messages that gradually decrease the volume. These can be deleted by a single click of the 'SUPPRESS volume control' button.

A pre-roll of -1000 ms has been added to introduce silence at the beginning of the object. However, the actual start of the object is at time 0, as indicated by its pivot (the red triangle).

The terminal symbol 'oscar2' has been added to the '-al.tryObjects' alphabet. If this had not been done, the machine would read "oscar2" as "oscar 2" and play 'oscar' followed by a two-beat silence!

The pivot is used to position 'oscar2' correctly in time. We will play for instance:

C4 _ _ oscar2

Let us set the position of the pivot at 800 ms of the beginning. This sets the first NoteOn (the first event of this object) to start 800 ms before the pivot location on the third beat:

👉 Be warned that the volume decreases at the end of this example. Your sound device may remain silent after the first playback. To avoid this, check the 'Reset controllers' option in the settings.

Cyclic sound-object

Let's take another look at the 'cycle1' sound object, which loops from 34% of its starting point. Play:

cycle1 _

We are calling 'cycle1' on 2 beats, but its option 'Never rescale' is checked. It will reach the expected duration by repeating its sequence of events, starting from 34% of its duration, as instructed:

The notes in this sound object are 'E4, G4, G4, A4, G4, Bb5'. The first two notes, 'E4 G4', are in the 34% area and are not repeated. The repetition therefore starts at 1.00 s with 'G4 A4 G4 Bb5'. However, to keep the total duration at 2.00 s, the second repetition is incomplete.

Let us create a copy of 'cycle1', called 'cycle1-force', which should extend itself with an integer number of repetitions.

(Don't forget to add it to the '-al.tryObjects' alphabet!)

Now play:

cycle1-force _

The duration now exceeds 2 beats in order to complete the 'G4, A4, G4, Bb5' repetition.

Cyclic sound objects play identically in both MIDI and Csound. All properties, such as pivot, pre-roll and post-roll, and effects, such as _transpose, _keyxpand and _keymap, are supported.

Below is an instance of cycle1 with a pre-roll of -100 ms and a post-roll of 300 ms. The grey parts are additional time segments that do not contain any event.

cycle1 _

Truncate the end of an object

Play this in MIDI and Csound:

C4 oscar2-trunc

Now let us add an 'f' sound-object which is not relocatable. As per the following score, it should be located with its pivot exactly on the fourth beat:

C4 oscar2-trunc -- f

However, the 'oscar2-trunc' sound-object is set to the 'Never cover end' option. It also has a 'Truncate end' option, set to accepting a truncation up to 50% of the sound's duration. This is an acceptable set of constraints:

A Trace file can be displayed, giving explanations about the time-setting process.

Read below the trace file for setting up 'C4 oscar2-trunc -- f':

Placing objects…
Col#5 side 1 Ts=5000 t1=3875 t2=4125 "f" should spend 1125 milliseconds, but no solution.
<
Col 3 NewTs=5000 ts1= 2000 ts2=2000 Tsm=5000 "-" This object is not the one concerned.<<
Col#2 nseq = 0 side = 2 ts = 1000 t1 = 1000 t2 = 5000 "oscar2-trunc"
We must save 1125 milliseconds
solution 1 ---------- SEQUENCE 1 ---------------------
#1 "C4" [0,1000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#2 "oscar2-trunc" [1000,3875] TruncBeg=0 TruncEnd=1125 alpha=1.000000 delta=0 DELTA=0
#3 "-" [2000,2000] TruncBeg=0 TruncEnd=0 alpha=2.000000 delta=0 DELTA=0
#5 "f" [3875,4125] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
---------- (time resolution = 1 ms) ------------

The trace indicates that 'oscar2-trunc' was truncated by 1125 ms at its end.

Now, let us try:

C4 oscar2-trunc f

The 'f' sound object needs to start on the second beat, which would cut off more than 50% of the end of 'oscar2-trunc'. There is no solution to this set of constraints. Therefore, the machine breaks the 'Non cover' limitation, yielding the following:

This is also explained in the Trace file:

Placing objects…
Col#3 side 1 Ts=5000 t1=1875 t2=2125 "f" should spend 3125 milliseconds, but no solution.
<
Col#2 nseq = 0 side = 2 ts = 1000 t1 = 1000 t2 = 5000 "oscar2-trunc"
We must save 3125 milliseconds
➡ We must release time constraint(s)!
• Releasing overlapping

Placing objects…
solution 1 ---------- SEQUENCE 1 ---------------------
#1 "C4" [0,1000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#2 "oscar2-trunc" [1000,5000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#3 "f" [1875,2125] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
---------- (time resolution = 1 ms) ------------

Since both the 'C4' note and the 'oscar2-trunc' sound-object are relocatable, we can figure out another solution that would not break an constraint:

This was generated by a modified version of the time-setting algorithm. In the correct version, this solution is not acceptable because it creates negative dates.

Truncate the beginning of an object

Let us now try to truncate the beginning of 'oscar2-trunc' by setting it no 'No relocate' and putting a 'crac' sound-object whose duration is slightly longer than 1 beat. The score of 'crac' is '{B3,D4}{C4,E4}'. We play:

crac oscar2-trunc

The picture is self-explanatory. The transition between 'crac' and 'oscar2-trunc' is smooth, because 'oscar2-trunc' starts sounding at the date of the first NoteOn(s) following the truncated part.

Try this longer truncation:

crac crac crac crac crac oscar2-trunc

Same result using 'oscar2-trunc-csound' which is a pure Csound object:

An out-time sound-object is never truncated:

crac << oscar2-trunc >>>

Truncating both ends of a sound-object

Try the following:

crac oscar2-trunc -- f 

If you are using the Event list, be aware that the start and end times displayed are those after truncation. To locate events correctly, you will need the 'trunc beg' and 'trunc end' values:

Let us truncate on both sides a pure Csound object playing 2 instruments:

crac oscar-2instruments - _tempo(1/4) f

Break tempo

Another solution to avoid issues with timings or sound objects being truncated is to authorise 'oscar2-trunc' to break the tempo. This technique is known as 'organum' in classical music performance. When this option is set on the 'oscar2-trunc' sound-object, we get:

The broken tempo is noticeable by the delayed position of the fifth streak (or beat).

This broken tempo will impose itself on any other sequences of events played on top of it. Play for instance:

{C4 oscar2-trunc f, D4 E4 B3 F3, A4 B4}

At first glance, it is surprising that the two sequences do not end on the same date. Note that 'F3' appears to be out of the picture. However, this bizarre result can be explained by counting beats. An expansion of the polymetric expression is the following:

_tempo(4) {C4_ _ _ oscar2-trunc_ _ _ f_ _ _ , D4_ _ E4_ _ B3_ _ F3_ _ , A4 _ _ _ _ _ B4_ _ _ _ _ }

The confusing factor is that the physical duration of 'f' is 0.25 s., with its pivot in the middle sitting on the beat labelled '3' (blue line). Notes in the 'D4 E4 B3 F3' sequence occupy 3 beats and their symbolic duration is 3/4 beat, whereas 'A4' and 'B4' occupy 1.5 beat. This is a typical example of the difference between symbolic duration (beats) and physical duration (seconds).

The process is summarized in the trace. The displacement of the third beat is marked as 'DELTA=3125':

Placing objects…
Col#9 nseq = 0 side = 1 ts = 5000 t1 = 1875 t2 = 2125 "f"
We must spend 3125 milliseconds
solution 1 ---------- SEQUENCE 1 ---------------------
#1 "C4" [0,1000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#5 "oscar2-trunc" [1000,5000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#9 "f" [5000,5250] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=3125
---------- (time resolution = 1 ms) ------------
Placing objects…
solution 1 ---------- SEQUENCE 1 ---------------------
#1 "C4" [0,1000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#5 "oscar2-trunc" [1000,5000] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
#9 "f" [5000,5250] TruncBeg=0 TruncEnd=0 alpha=1.000000 delta=0 DELTA=0
---------- (time resolution = 1 ms) ------------
Placing objects…
solution 1 ---------- SEQUENCE 2 ---------------------
#1 "D4" [0,750] TruncBeg=0 TruncEnd=0 alpha=0.750000 delta=0 DELTA=0
#4 "E4" [750,1500] TruncBeg=0 TruncEnd=0 alpha=0.750000 delta=0 DELTA=0
#7 "B3" [1500,5375] TruncBeg=0 TruncEnd=0 alpha=3.875000 delta=0 DELTA=0
#10 "F3" [5375,6125] TruncBeg=0 TruncEnd=0 alpha=0.750000 delta=0 DELTA=0
---------- (time resolution = 1 ms) ------------
Placing objects…
solution 1 ---------- SEQUENCE 3 ---------------------
#1 "A4" [0,1500] TruncBeg=0 TruncEnd=0 alpha=1.500000 delta=0 DELTA=0
#7 "B4" [1500,6125] TruncBeg=0 TruncEnd=0 alpha=4.625000 delta=0 DELTA=0
---------- (time resolution = 1 ms) ------------

Continuity property

A sound-object can be instructed to 'stick' to the preceding and/or the next event in the sequence. These properties are known as 'Continuity at the beginning' and 'Continuity at the end'. The 'glue' sound-event is of this kind. Play:

cycle1-force _ - glue

The 'glue' sound object was supposed to be placed on the fourth beat, but it ended up at the end of 'cycle1-force'.

A refinement of this process is the allowance for a maximum gap at the beginning or the end of a sound-object. These properties are known as 'Allow gap'.

Tonal scale

A detailed presentation of this topic is on this page. The tonality can be controlled in both Csound and real-time MIDI productions (read more). The good news is that (micro)tonal adjustements can be applied to both MIDI and Csound sound-objects.

Let's consider an example where the difference is obvious: the Bohlen-Pierce scale, in which the octave is replaced with a tritave (ratio 3/1) and it is divided in 13 intervals. Let us play the following in both MIDI and Csound:

_tempo(0.66) G3 C4 oscar - _scale(Bohlen-Pierce,60) G3 C4 oscar

The '60' in the _scale instruction means that the block key is the middle of a standard keyboard (more details). So, 'C4' is rendered at the same frequency in both the standard equal-tempered scale and the Bohlen-Pierce scale.

The event list of this performance can be downloaded here.

Note that the pianorolls of both parts are identical, because tonal corrections are done after drawing the pictures.

Serial tools

Serial tools such as _retro, _rotate, etc., modifying the order of sound-objects (read documentation) do not modify the order of events inside each sound-object.

Other serial tools are accepted by 'oscar', as shown by its settings.

The same effects are applied to Csound productions, whether converted from MIDI or using the object's Csound score.

Play this in both MIDI and Csound:

oscar - _transpose(3) oscar

Play in Csound:

oscar-purecsound - _transpose(3) oscar-purecsound

Check this in both MIDI and Csound:

oscar - _keyxpand(F#4,-1) oscar

More complex:

oscar - _keymap(C4,C2,C6,C7) oscar

Various effects

The _pitchbend() command has no effect on sound-objects. This is on the agenda.

Play this superposition of two occurrences of 'oscar' displaced by a few milliseconds, both in MIDI and Csound:

{oscar, 2/10 oscar}

Modify MIDI codes in a sound-object prototype

Bottom of the page of a sound-object prototype and its graphic display
  • At the bottom of each sound-object prototype page, the EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes links display the lists of MIDI instructions and time-stamped bytes that will be sent to the MIDI driver. (The first number is actually the number of bytes.)
  • 👉  Don't forget that the “-so” file is saved in the background every 30 seconds (autosave) while you are modifying sound-object prototypes… To return to the original version, close the “-so” tag and restore the “-so” file from its copy!
  • The IMAGE link displays an image of the sound-object prototype along with indications of its topological and metrical properties, similar to the BP2.9.8 interface.
  • The Play MIDI file link produces a sound output based on MIDI events contained in the sound-object prototype. Here, the "chik" sound-object prototype plays a 250 ms chord on a stringed instrument. The interface uses the MIDI player to do this.
  • Note that there are five "Channel pressure" MIDI instructions in this sound-object. These may have been picked up by playing on a pressure-sensitive keyboard and their relevance is low since channel pressure can be controlled at a higher level by performance parameters. It is therefore advisable to click on SUPPRESS channel pressure and check the effect on EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes. If the change is not immediately visible (this depends on the browser), simply reload the pop-up window. Other "continuous" parameters such as "volume control" can be suppressed in a similar way.
  • APPEND AllNotesOff (all channels) can be a useful option to ensure that this object turns off all pending notes on the sound machine. It sends an instruction to each of the 16 channels.
  • The MIDI content of this object can be changed by loading a MIDI file. Click Choose File to select a MIDI file — for example, "test.mid" in the "ctests" folder — and then send to upload it. It is not finalised immediately: you can examine the EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes of this file before saving it to the sound-object prototype. The example "test.mid" contains no less than 432 bytes because of the "Channel pressure" and "Parameter ctrl 7" messages, which control pressure and volume. You can accept the import by clicking SAVE or cancel it by clicking CANCEL. There is currently no "undo" function in case the MIDI sequence has been replaced or deleted by mistake.
  • An important feature is QUANTIZE NoteOns. We are dealing with "striated sound-objects", which means that they are designed to be played at a certain tempo. The tempo at which the MIDI content of this object was captured is generally not the same as the tempo at which it will be played, as the latter depends on performance parameters. The reference tempo is given by Tref which in this case is 1000 ms for a metronome with 60 beats/mn. The MIDI content uploaded by "test.mid" has a duration of 3500 ms, i.e. 3.5 beats. This duration can be set either in milliseconds or in beats. Regardless of the duration, it is often convenient to locate NoteOn and NoteOff events to a precise fraction of a beat. An Quantizing to 1/64th of a beat is often a good choice. For simplicity's sake, we will set it to 1/50th of a beat, or 20 ms.
    Before clicking on QUANTIZE NoteOns, check the EXPLICIT MIDI codes. You will notice that there is a NoteOn of key 62 at 804 ms and a NoteOff of key 60 at 825 ms. Set the quantization to 1/50th of a beat and click QUANTIZE NoteOns. Now the timings of these events have been changed to 800 ms and 820 ms respectively, which are multiples of 20 closest to the original timings.

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 Csound outputs.

Set it up

When 'Event list' is selected on a Data or Grammar page, sound events are saved to a CSV file. The full description of the sound object prototypes used in production is saved to a JSON file. All used tonal scales are exported in Scala (SCL) and keyboard mapping (KBM) formats. Any Csound instrument used for the production of Csound score is exported as a JSON file.

The event list file

Click PRODUCE ITEM(s) on a grammar page, here for instance '-gr.koto3'. This yields:

No sound output (MIDI or Csound) has been produced. Instead, a file called 'koto3.csv' is available in the 'my_output' folder (by default). You can visualise this file by clicking the 'output file' link, or download it (get it here) for later use.

The event list contains many columns, a number which is likely to increase with new developments. It looks like this:

Beginning of the koto3.csv event list file

Each line of the event list is assigned to a sound-event with start and end times in milliseconds, as shown on the graphic display:

The labels 'a' and 'b' designate sound-objects, with respective prototype identifiers 3 and 5, as defined in the related '-so.abc1' file. The item labelled 'Y' is a silent sound-object created to represent the residual variable 'Y'.

The examples on this page may not contain all the information provided in the latest version of the event lists because the format is frequently updated.

The timings of sound-objects and simple notes in the event list are the accurate ones computed by the polymetric expansion and time-setting algorithms. Serial tools (e.g. _retro) modifying the order of events have been applied. However, serial tools modifying pitches (e.g. _transpose) have not been applied; therefore, their parameters are given in the event list. The second-to-last column contains the name of the tonal scale, if any (see below).

The sound-object file

The '-so.abc1' file, which is used to define all the sound objects used in the '-gr.koto3' project, is in an unfriendly format produced by the PHP interface. Therefore, to facilitate further use, it is exported to a more readable JSON format ('proto-abc1.json'):

Top of the 'proto-abc1.json' file

Please note that each sound-object is identified by both a label and a numeric identifier. These parameters are displayed in columns 4 and 5 of the event list. Numbers make it easier to match objects in the event list with their descriptions in 'proto-abc1.json'.

👉 Since numeric identifiers are created when the alphabet is compiled, the values appearing in 'proto-abc1.json' are specific to the '-gr.koto3' project.

The tonal (scale) files

SCL and KBM files are produced wherever tonal scales are used in the production (read MIDI microtonality).

Let's try the '-da.Ombres_errantes' project. Check the 'Event list' output format and click 'PLAY'. Links for downloading the rameau_en_sib.scl and rameau_en_sib.kbm files are displayed:

If several scales have been used in the production, several download lines will be displayed.

👉 These SCL and KBM file can also be exported via the tonality editor in the interface. The 'rameau_en_sib' scale is defined in the '-to.tryTunings' tonality framework which is displayed as follows:

(Click the EDIT button to reach the export to KBM)

The Csound instrument files

If a Csound resource file is declared at the top of the project, the full descriptions of instruments used in the production of items are exported to a JSON file.

For example, in '-da.tryMiscObjects', the '-cs.tryTunings' Csound resource is declared. Let us play the following with the 'Event list' output option. 

_ins(1) C3 _ins(2) D3 _ins(3) G3 _ins(Synth_brass) D3 _ins(267) E3

The _ins() instructions are calling several instruments described (or not) in '-cs.tryTunings':

  • Instrument 1 is 'Plucked_string1'
  • Instrument 2 is 'Plucked_string2'
  • Instrument 3 is 'Synth_brass'
  • Instrument 267 does not exist

These instruments are mentioned in the 9th column of the event list (see below). Their JSON files are exported and links are supplied to download them.

This result can be verified by clicking on the EXPAND button (near the PLAY button), as it explicitly reveals which instruments will be used:

_ins(Plucked_string1) C3 _ins(Plucked_string2) D3 _ins(Synth_brass) G3 _ins(Synth_brass) D3 _ins(Plucked_string1) E3

Using sound-objects that contain Csound scores opens up more possibilities. These Csound scores contain instrument numbers in their first column.

An option named 'GLOBAL_CS' tells the machine to use the instruments set by the context. This is the case of instrument 'oscar-purecsound'. Consequently, playing:

_ins(1) oscar-purecsound -- _ins(2) oscar-purecsound -- _ins(3) oscar-purecsound

will produce the following list of events:

and the following Csound score, in which instruments are tagged in the first argument of each line:

t 0.000 60
i1 0.000 1.365 9.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D5
i1 0.227 0.228 8.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F4
i1 0.227 0.228 7.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F3
i1 0.227 0.683 6.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#2
i1 0.455 0.227 8.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#4
i1 0.455 0.227 7.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#3
i1 0.682 0.114 8.09 90.000 90.000 0.000 0.024 0.024 0.000 ; A4
i1 0.682 0.114 7.09 90.000 90.000 0.000 0.024 0.024 0.000 ; A3
i1 0.796 0.114 8.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#4
i1 0.796 0.114 7.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#3
i1 0.910 0.455 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 0.910 0.910 8.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G4
i1 1.441 0.076 9.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G5
i1 1.441 0.076 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 1.517 0.075 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 1.517 0.075 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i1 1.592 0.076 10.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D6
i1 1.592 0.076 8.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D4
i1 1.668 0.076 10.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C6
i1 1.668 0.076 8.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C4
i1 1.744 0.076 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 1.744 0.076 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i2 3.000 1.365 9.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D5
i2 3.227 0.228 8.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F4
i2 3.227 0.228 7.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F3
i2 3.227 0.683 6.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#2
i2 3.455 0.227 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i2 3.455 0.227 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i2 3.682 0.114 8.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A4
i2 3.682 0.114 7.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A3
i2 3.796 0.114 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i2 3.796 0.114 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i2 3.910 0.455 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i2 3.910 0.910 8.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G4
i2 4.441 0.076 9.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G5
i2 4.441 0.076 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i2 4.517 0.075 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i2 4.517 0.075 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i2 4.592 0.076 10.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D6
i2 4.592 0.076 8.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D4
i2 4.668 0.076 10.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C6
i2 4.668 0.076 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4
i2 4.744 0.076 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i2 4.744 0.076 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i3 6.000 1.365 9.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D5
i3 6.227 0.228 8.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F4
i3 6.227 0.228 7.05 90.000 90.000 0.000 0.012 0.012 0.000 ; F3
i3 6.227 0.683 6.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#2
i3 6.455 0.227 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i3 6.455 0.227 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i3 6.682 0.114 8.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A4
i3 6.682 0.114 7.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A3
i3 6.796 0.114 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i3 6.796 0.114 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i3 6.910 0.455 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i3 6.910 0.910 8.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G4
i3 7.441 0.076 9.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G5
i3 7.441 0.076 7.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G3
i3 7.517 0.075 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i3 7.517 0.075 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
i3 7.592 0.076 10.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D6
i3 7.592 0.076 8.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D4
i3 7.668 0.076 10.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C6
i3 7.668 0.076 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4
i3 7.744 0.076 9.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#5
i3 7.744 0.076 7.10 90.000 90.000 0.000 0.012 0.012 0.000 ; A#3
s

Another option named 'LOCAL_CS' tells that the Csound instruments listed in the sound-object's score should be used. This is the case of 'oscar-2instruments' which uses two instruments. So, playing:

_ins(2) C4 - oscar-2instruments - D4

will produce the following event list:

and a Csound score making it clear that notes C4 and D4 are performed with instrument #2, as instructed by ins(2):

t 0.000 60
i2 0.000 1.000 8.00 90.000 90.000 0.000 0.012 0.012 0.000 ; C4
i3 2.000 1.365 9.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D5
i1 2.227 0.228 8.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F4
i1 2.227 0.228 7.05 90.000 90.000 0.000 0.024 0.024 0.000 ; F3
i1 2.227 0.683 6.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#2
i3 2.455 0.227 8.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#4
i3 2.455 0.227 7.06 90.000 90.000 0.000 0.012 0.012 0.000 ; F#3
i3 2.682 0.114 8.09 90.000 90.000 0.000 0.012 0.012 0.000 ; A4
i1 2.682 0.114 7.09 90.000 90.000 0.000 0.024 0.024 0.000 ; A3
i1 2.796 0.114 8.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#4
i1 2.796 0.114 7.06 90.000 90.000 0.000 0.024 0.024 0.000 ; F#3
i1 2.910 0.455 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 2.910 0.910 8.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G4
i3 3.441 0.076 9.07 90.000 90.000 0.000 0.012 0.012 0.000 ; G5
i1 3.441 0.076 7.07 90.000 90.000 0.000 0.024 0.024 0.000 ; G3
i1 3.517 0.075 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 3.517 0.075 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i1 3.592 0.076 10.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D6
i1 3.592 0.076 8.02 90.000 90.000 0.000 0.024 0.024 0.000 ; D4
i1 3.668 0.076 10.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C6
i1 3.668 0.076 8.00 90.000 90.000 0.000 0.024 0.024 0.000 ; C4
i1 3.744 0.076 9.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#5
i1 3.744 0.076 7.10 90.000 90.000 0.000 0.024 0.024 0.000 ; A#3
i2 4.000 1.000 8.02 90.000 90.000 0.000 0.012 0.012 0.000 ; D4
s

In this example, the 'LOCAL_CS' mention in the 9th column indicates that the sound-object will use its own Csound instruments. These instruments are found in its score. In addition, the three files required for the performance have been exported: 'instr-Plucked_string1.json', 'instr-Plucked_string2.json' and 'instr-Synth_brass.json'. The index of each instrument is mentioned as 'CsInstrumentIndex' in each file.

An example of JSON instrument file is 'instr-Vina.json' produced by '-gr.vina3'.

Using command lines

Event lists and related files can be produced by calling the console via (Unix) command lines. For example,

./bp produce -se ./ctests/-se.koto3 -gr ./ctests/-gr.koto3 -al ./ctests/-al.abc1 -so ./ctests/-so.abc1 --eventlistout ./my_output/koto3.csv --traceout ./temp_bolprocessor/trace_my_session_my_project.txt

This will produce 'koto3.csv' and 'proto-abc1.json' in the 'my_output' folder. (If the --traceout option is not specified, no image will be created.)

./bp play -se ./ctests/Imported_MusicXML/-se.Ombres_errantes -da ./[your_path]/0.bpda -to ./tonality_resources/-to.tryTunings --eventlistout ./my_output/Ombres_errantes.csv --traceout ./temp_bolprocessor/trace_8510fe8339_-da.Ombres_errantes.txt --traceout ./temp_bolprocessor/trace_my_session_my_project.txt --english

This will produce 'Ombres_errantes.csv', 'rameau_en_sib.scl' and 'rameau_en_sib.kbm' in the 'my_output' folder. (If the --traceout option is not specified, no image will be created.)

When calling this production via a command line, we need to find out the names of scale files. Since 'rameau_en_sib' is not found in the command, a scan of the data or grammar is necessary to detect _scale(rameau_en_sib, …) instruction(s). If several scales are used in the production, each of them will export a pair of SCL and KBM files that can be identified in the same manner.

Designed by Bernard Bel, version 3.5.6 (Fall 2026)

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 serial tool approach makes it possible to carve "shapes" in the time and pitch dimensions of a musical work containing simple notes and/or sound-objects. These tools were first implemented in the late 1990s, following suggestions from the Dutch composer Harm Visser.

Serial tools are applied immediately after the production process for a musical piece, and before the expansion of its polymetric structures. Therefore, they are ignored during the production.

All tools in the current implementation (version 3.5.2 and later) are applied recursively to the fields of polymetric structures.

Tools modifying the order of sound-objects

_retro

_retro C0 C2
_retro {C0 C2}

both produce:

C2 C0

 

Note the propagation in polymetric structures:

_retro {a b {c d, C4 D4}} 1/4

produces:

1/4 { { d c,D4 C4 } b a }

Here, sound objects a, b, c and d were mixed with the simple notes C4 and D4. Consequently, the timing of the final structure is influenced by the metrical and topological properties of these sound objects.

The cascading effect of _retro can be difficult to figure out. For example,

_retro a b _retro c d _retro A4 B4

will produce:

 c d b a B4 A4

whereas

_retro {a b _retro {c d _retro {A4 B4}}}

will produce:

c d B4 A4 b a

_ordseq

This tool restores the order of the following sequence (or polymetric structure) if it has been subject to change by _retro, _rndseq or _rotate. For example,

_retro {A3 B3, C5 D5 _ordseq C4 D4} F4

will produce:

F4 {B3 A3, C4 D4 D5 C5} F4

_rndseq

_rndseq a b c d

will put the sequence in an unpredictable order, for instance:

a d b c

If a positive integer is set as the seed for randomisation in the project settings, the same order will appear each time the production is launched. In our comparative tests, we use seed = 1, which produces the same "random series" in all systems.

Beware that

_rndseq A4 B4 C4 _rndseq A5 B5 C5 D5

is interpreted as:

_rndseq A4 B4 C4 {_rndseq A5 B5 C5 D5}

where the "{_rndseq A5 B5 C5 D5}" expression is a fifth unit, which may yield (depending on the seed):

B4 B5 D5 A5 C5 C4 A4

and not:

_rndseq{A4 B4 C4} _rndseq{A5 B5 C5 D5}

which may yield:

C5 B5 D5 A5 B4 C4 A4

Using curled brackets to mark out sequences is a good idea!

_randomize

This instruction cancels the fixed randomisation setting. In fact, it shuffles the cards and sets the seed to 0. Example of proper use:

_randomize _rndseq a b c d

_rotate

_rotate(x) rotates the following sequence by x units. If x = 2, the rotated sequence will start after the first 2 units, which will be sent to the end. Thus,

_rotate(2) C4 D4 E4 F4

will produce:

E4 F4 C4 D4

and

_rotate(-1) C4 D4 E4 F4

will produce:

F4 C4 D4 E4

This one:

_rotate(-1) {_rotate(2) _rotate(-1) a b c d}

will produce "a b c d" because -1 + 2 -1 = 0.

The _rotate instruction is propagated to all fields of polymetric structures. Thus,

_rotate(-1) {A4 B4 C4 D4, A2 B2 C2}

will produce:

 {D4 A4 B4 C4, C2 A2 B2}

Be aware that "units" may be simple notes, sound-objects, polymetric structures or structures that are preceded by another serial tool. For example,

_rotate(2) {A4 B4 _rotate(-1) C4 {D4 E4} F4, A3 B3 C3} F5 G5

produces:

G5 { { E4 D4 } F4 C4 A4 B4, C3 A3 B3 } F5

Explanation: The "C4 {D4 E4} F4" and "D4 E4" sequences rotate by 1 unit because 2 - 1 = 1. The "A3 B3 C3" sequence rotates by 2 units. The "_rotate(-1) C4 {D4 E4} F4" expression is treated as a single unit in the rotation by 2 units of "A4 B4 _rotate(-1) C4 {D4 E4} F4".

Tempo and speed markers are treated as "units" in the rotation. Thus,

_rotate(-1) C4 D4 _tempo(3/2) E4 F4 G4

produces:

G4 C4 D4 _tempo(3/2) E4 F4

Units moved by _rotate, _retro or _rndseq can also be silences or silent sound-objects, for instance:

_rotate(-1) {- b a c d, a b c'} d'

which produces:

 d' { d - b a c, c' a b }

Upgrade of the Zouleb() procedure (geeks only)

'Zouleb' is an anagram of 'Boulez', in honour of Pierre Boulez, who championed the composition of serial music.

Until version 3.5.2 was released in August 2026, the Zouleb() procedure in Zouleb.c used a different syntax for tools such as _rotate, which ignored the field separator ','.

If you wish to try the old procedure, check the Ignore field separators option in the SERIAL TOOLS section of the settings. This option is set on the old projects -gr.Visser.Shapes and -gr.Visser.Waves (read page).

For example,

_rotate(1) {A4 B4 _rotate(1) C4 F4 G4, A3 B3 C3}

produces

{B4 G4 C4 F4 A4, B3 C3 A3}

with the current procedure, whereas the old procedure produced:

{B4 G4 C4 F4,A3 B3 C3 A4}

Tools modifying pitches

_transpose

_transpose(n) shifts the following sequence up by n steps (not necessarily semitones). For example,

_transpose(4) C4 D4 E4

produces:

E4 F#4 G#4

Sound-objects can also be transposed if their "Accept transposition" option is set. For example,

c a b - _transpose(6) c a b

This and other pitch-modifying tools deal with steps of the scale. These are semitones only in 12-tone scales. Try for example a 13-tone scale:

-to.tryScales
_scale(Bohlen-Pierce,0) _transpose(1) C4 Db4 D4 E4 F4 Gb4 G4 H4 Jb4 J4 A4 Bb4 B4 C5

which produces:

Db4 D4 E4 F4 Gb4 G4 H4 Jb4 J4 A4 Bb4 B4 C5 Db5

_keyxpand

_keyxpand(basenote, ratio) multiplies melodic intervals by ratio (positive or negative) relative to the basenote. For example,

_keyxpand(C4, 2) D4 E4 F4 

produces:

E4 G#4 Bb4

The basenote parameter can be an explicit note, as shown above, or a key number ranging from 0 to 127. For instance, if C4 is mapped to the value 60 in the settings, it can be replaced by 60:

_keyxpand(60, 2) D4 E4 F4

_keyxpand is applied recursively to the fields of a polymetric expression. The values of ratio are cumulated multiplicatively if the centre note is the same. For instance,

_keyxpand(C4,-2) B3 C4 { _keyxpand(C4,-1) D4 E4 }

produces:

D4 C4 E4 G#4

i.e. the same as:

_keyxpand(C4,-2) B3 C4 _keyxpand(C4,2) { D4 E4 }
or _keyxpand(C4,-2) B3 C4 _keyxpand(C4,2) D4 E4

 

See -gr.tryKeyXpand for a typical example containing notes and sound-objects. The beginning of the piano roll produced by this grammar provides an approximate overview of the process:

The "ratio" parameter can be any floating-point number, positive or negative. For example,

_keyxpand(C4,-1.80) D4 E4

will produce:

G#3 F3

The two-semitone distance between C4 and D4 has been transformed to 2 × -1.8 = -3.6, which has been rounded down to -4, yielding G♯3. Similarly, the four semitones between C4 and E4 have been transformed to 4 × -1.8 = -7.2, which has been rounded up to -7, yielding F3.

Algebra

Let 'k' be the key number of 'basenote'. The following equation is used to change a note whose key number is 'x' to a note whose key number is 'y':

y = x + ratio . (x - k)

Key expand interpolation

👉   This feature is not yet implemented in BP3, but we plan to offer it in consistent with key mapping interpolation (see below).

_keymap

Syntax: _keymap(p1,q1,p2,q2)

In the sequence, this tool modifies pitches in range (p1,p2) according to a linear mapping in which q1 is the image of p1 and q2 the image of p2.

The tool makes changes on "simple notes" and on "sound-objects" in which the property "Accept key changes" has been set to true.

p1, q1, p2, q2 may be written as integers (key numbers) in range 0..127, or simple notes using the current note convention. The _keymap(p1,q1,p2,q2) syntax demands that p2 > p2, or the equivalent notes are in ascending order. For instance, both expressions:

_keymap(C3,E4,C5,C6) C4 B3 A3
and _keymap(48,64,72,84) C4 B3 A3

produce:

D5 C#5 C5

Algebra

Given _keymap(p1,q1,p2,q2) where p1, q1, p2 and q2 are key numbers, the following equation is used to change a note whose key number is 'x' to a note whose key number is 'y':

y = a x + b
with a = (q2 - q1) / (p2 - p1)
and b = q1 - a p1

In the example above, a = 5/6 and b = 24. Thus, C4 (60) is converted to D5 (74), B3 (59) to C#5 (73 after rounding from 73.16), and A3 (57) to C5 (72 after rounding from 71.5).

Changes to sound objects can be visualised using the -gr.tryKeyMap grammar by clicking the 'TryThis' button at the bottom of the page. The following sequence is played:

TryThis --> _keymap(52,86,86,52) a -- b

Sound-objects 'a' and 'b' (defined in -so.tryKeyMap) are identical except that "Accept key changes" is checked for 'a' and unchecked for 'b'. Therefore, 'b' is not modified:

Keymap interpolation

Changes can be made continuous using _mapcont and _mapstep instructions, and discrete again with _mapfixed. The parameters p1, q1, p2 and q2 are interpolated between two _keymap instructions.

Instructions _mapcont and _mapstep are equivalent when dealing with simple notes. However, _mapcont also modifies pitches inside the sound-objects whose option "Accept key changes" is checked.

Let's see an example easy to visualise because of the repeated pattern "C4 C#4 D4 G4":

_tempo(6) _mapcont _keymap(C3,C3,C5,C5) C4 C#4 D4 G4 C4 C#4 D4 G4 C4 C#4 D4 G4 C4 C#4 D4 G4 _keymap(C3,C2,C5,C6)

Same process using sound-objects: click the 'TryThis2' button at the bottom of the -gr.tryKeyMap grammar. The following sequence is played:

TryThis2 --> _mapcont _keymap(52,52,86,86) a a a _keymap(52,86,86,52)

Since the 'a' sound-object accepts key changes, it is modified by _keymap with parameters p1, q1, p2 and q2 interpolated between the two values. The interpolation is computed again for each note. This produces:

Grammar -gr.tryKeyMap is a more elaborated example containing notes and sound-objects. The beginning of the piano roll produced by this grammar provides an approximate overview of the process:

« Translate