
This is a presentation of Bol Processor BP3. Download packages, install a local Apache server and check these procedures in your environment: MacOS, Windows, Linux etc.
➡ Send questions/suggestions to developers via the contact form or join the BP developers list on SourceForge. Errors should be reported to Git issues for a quick fix.
The current version of ‘BP3’ Bol Processor produces BP scores, standard MIDI files and Csound scores. MIDI files can be heard immediately owing to the in-built MIDIjs player, and Csound scores are automatically converted to sound files sent to a standard HTML5 audio player.
The present page is a survey of all interactions with the Bol Processor BP3 ‘bp’ console. The aim is to check its operation in any environment eligible to compiling the core program (i.e. the console). All features are currently developed and verified under MacOS. We need testers for Windows and Linux environments.
After completing and checking the installation of BP3 and (optionally) Csound, feel free to read and verify these features in a random order…
The next major stage of development will be the production of a standalone application built on PHP/HTML/Javascript code used in this demo.
Install the package
Installing Bol Processor BP3 does not require any programmer’s skills. Notably, no need of Unix commands sent via the Terminal… Only follow the 7 steps with great care.
- To use Bol Processor BP3 you need to install an Apache+PHP package on your desk computer:
https://en.wikipedia.org/wiki/List_of_Apache-MySQL-PHP_packages
This will allow you to run a local web service. Geeks may indeed install Apache and PHP on their own…
At the moment, Bol Processor cannot be used on shared websites because most (affordable) hosting services do not accept binary applications. - On Mac and Windows machines we recommend MAMP or XAMPP, both Apache/PHP servers with pre-installed features. Only Apache and PHP (with the GD Graphics option) need to be running, since no database is used by this interface. MAMP requires a payment after for two weeks, although XAMPP is entirely free of charge …
➡ Don’t try the virtual machine version of XAMPP! It won’t work on Macs using M1 (and above) chips. Use the native installer.
➡ In case you wish to run Apache automatically when starting your computer, this process is easy with MAMP yet a bit more complex with XAMPP. Mac users can create a startup script to this effect. Windows users, try this method, and Linux Ubuntu users that method… - Download the latest versions of files for the PHP interface: php-frontend-master.zip and the sample set bp3-ctests-main.zip. These files are regularly updated. All updates are announced on the BP developers list and major updates uploaded to the GIT repository.
- After unzipping these packages, create a “bolprocessor” folder at a location suitable for your local web server — for instance, inside the “localhost” or the “htdocs” folder created by XAMPP or MAMP.
- At the top level in the “bolprocessor” folder, create folder “ctests”. Copy the content of “php-frontend-master” to the “bolprocessor” folder and the content of “bp3-ctests-main” to “ctests”.
Now, inside “bolprocessor” you should see:- The “php” folder
- The “BP2_help.txt” file
- The “LICENSE” file
- The “README.md” file
- The “compile.php” file
- The “ctests” folder containing a set of examples of Bol Processor: grammars, alphabets, data, sound-object prototypes, etc. You may include any file previously saved with the BP2.9.8 application.
- The “csound_resources” folder containing Csound orchestra files and instruments, their attached waveform files etc. BP3 automatically moves Csound resources to this folder in case it finds them in a data folder. This avoids duplicating material and creating conflicts.
- Download the console package from GitHub — namely, bolprocessor-graphics-for-BP3.zip — and unzip it. Then copy its entire content to the “bolprocessor” folder. It includes the C source files that will be compiled to create the “bp” console (path: source/BP2). It also contains files used in older versions.
- Make sure that the “bolprocessor” folder and all files it contains have read/write permissions for all users — numeric mode “777″ — failing to which you might get blank pages or a notification such as “error 500″. Carefully set permissions of the “bolprocessor” folder to read/write including its subfolders and files.
➡ There is no security risk changing these permissions, since the Apache server will be running on your private computer. Bol Processor BP3 never creates/modifies files outside its “bolprocessor” folder.

The setup of files is displayed on the left. This picture includes “bp” that will be created later.
Folders “temp_bolprocessor” and “my_output” will be automatically created when running the interface. The content of folder “temp_bolprocessor” is cleared of all files older than 24 hours.
Save a copy of the “ctests” folder because you will probably modify some data files while using the program. Later you may wish to restore initial versions.
Running the interface will also create “BP2_help.html” in the “php” folder using “BP2_help.txt” as its source. Therefore, the latter should always remain at the top of the “bolprocessor” folder.
If you plan to check the production of Csound scores and associated sound files, a Csound installation is required. Packages are available for all systems on the Csound’s download page. If you don’t feel comfortable compiling source code, select a ready-made installation. For instance, the OS X dmg archive installs Csound in a single click on Macintosh computers; this does not require any technical skill.
➡ Due to a design error, Csound versions 6.16 and 6.17 did not work when called from a web browser. This problem has been solved with Csound 6.18. Make sure you have a compatible version in case Csound is already installed on your computer. Updating to the latest version is a good idea!
Start your local Apache server
The following are explanations for Mac users, which should easily be convertible to Windows and Linux — your suggestions are welcome!
If you installed MAMP, starting the Apache server is quite simple:

- Launch MAMP (or MAMP PRO) in the Applications folder.
- Click the activation button for Apache on MAMP’s main window (see picture).
- The picture shows default settings for PHP which has been launched along with Apache. Version 7.4.2 is the highest version currently supported by MAMP PRO (and 2022).
If you installed XAMPP, you need to open the XAMPP folder in the Applications folder, then launch manager-osx.app as shown on the picture below.
The XAMPP main page will show up. Click the Manage Servers tab, then select Apache Web Server and click Start.

Once Apache is running, you can click the Welcome tag and the Go to Application button. This should display a (local) page about XAMPP located on path http://localhost/dashboard. Both dashboard and bolprocessor folders are located in folder Applications/XAMPP/xamppfiles/htdocs.
➡ You cannot run both MAMP and XAMPP Apache servers at the same time because they use the same port (80). This wouldn’t be a meaningful idea anyway…
Compile ‘bp’ and check its operation

- Launch your Apache/PHP server (read previous chapter) and point your (favourite) web browser at file bolprocessor/php/index.php. The URL will look like http://localhost/bolprocessor/php/. Note that “http” is used, not “https”.
- If you get an error message or see nothing, check point 7 (file permissions) of the installation procedure above.
- The first time, you will not see the home page as shown above. Instead, you will get a warning that “bp” has not been found — or is not properly responding on your system — along with a link to the “compile.php” page. This page will attempt a compilation of “bp” if the “source” folder has been properly copied to “bolprocessor” (step 6 above). This compilation runs the “make” command of your system, reading the “Makefile” set of instructions.
➡ This process works nicely on MacOS. We need your help to adapt it to other environments. Please share your experience! - Mac users: if the compilation fails, you may need to install command line developer tools in OS X (explanations) or the Xcode toolkit (read Bent Petersen’s instructions) on your machine.
- Once “bp” has been created, the home page will display the content of the “bolprocessor” folder, notably the “ctests” folder. If Csound is installed and responsive, a friendly warning will be displayed on the top right along with a mention of its version (see picture above).
- Follow the “ctests” link. It will display a list of available sample files. Their names are tagged with color labels indicating the type of each file. Generally, a Bol Processor grammar’s name starts with “-gr” but it may as well end with extension “bpgr”. Both conventions of file types are supported by BP2 and BP3. This had become necessary, long time ago, when upgrading from MacOS 9 to MacOS 10…

- Click “-gr.koto3″ to open a grammar. This will automatically create a “my_output” folder at the top of the “bolprocessor” folder in case it wasn’t already there. Try to create an output folder with a different name and verify its presence at the top of “bolprocessor”. The output folder’s current name is saved in “_settings.php” which is recalled each time the interface is used. Failure to modify settings and/or to create output folders would reveal a bad configuration of file permissions on your local web server.
- You can create subfolders of the current output folder. If the current output is set to “my_output”, create for instance “my_output/todays_folder”. The interface automatically replaces spaces with ‘_’ as these may be unwanted on some systems.
- Verify that the “bp” console is responding appropriately by clicking the link to console’s help file at the top right of the page. The help will appear on a pop-up window. Pop-up windows created by Bol Processor should be visible irrespective of security settings on your web browser.
- Failure to respond would indicate that the compilation wasn’t appropriate.
- If you need to recompile “bp” on a Mac, you can simply open the page http://localhost/bolprocessor/compile.php which automatically launches the “Makefile” system command.
- The Grammar page has a temporary Test image link showing a pop-up window with drawings, texts and animation. This is used for checking cross-platform compatibility.
Produce items


- Open the “-gr.koto3″ grammar and click PRODUCE ITEM(s). This will open a “BP console” pop-up window and call the console application.
- If the console application is running, a detailed list of actions will flow on the pop-up window. One of them is “Errors: 0″ indicating that the running was faultless. It should be faultless with this example. On top of the window, the command line created to call the console is displayed in red color. This is used by programmers for checking the response of the console.
- An “Image” link appears at the top of the BP console window. Click it to display the image on a new window. By default, the image displays sound-objects a, b, c etc. We will see later a pianoroll another option.
- By default, the output was set to MIDI files. A link is supplied to download this MIDI file, and a javascript MIDIjs player is shown to listen to its content. In the absence of “MIDI program” messages, piano-like sounds are produced which do not resemble the rendering of the -“gr.koto3″ grammar on a proper MIDI device — here a Roland D-50 synthesizer, listen to examples.
- At the top of “BP console” a link points to the “trace file” showing the full process of derivations for creating the item. It has been created because the “--trace-production” option had been appended to the command line for the sake of checking details. The Trace mode can be enabled or disabled on the “-se.koto3″ settings page.
- Check the “bolprocessor/my_ouput” folder. It should contain “koto3.mid” — the default name for this MIDI file.

- Return to the grammar and select the “BP data file” option for the output, then click the SAVE button. Now the name “koto3.bpda” will be created, but you can change it to anything while keeping the “bpda” extension, or use the “-da” prefix instead.
- Click again the PRODUCE ITEM(s) button. A link to the data file in Bol Processor score notation appears on the top (see picture). The Trace file displays the same derivations. File “koto3.bpda” should also be visible in the bolprocessor/my_ouput folder.
- If you return to the tag displaying the content of the “ctests” folder, you can click the “[move up]” link and enter the “my_output” folder. There you will see “koto3.mid” and “koto3.bpda” which have just been created. Because of its “bpda” extension, the data file has a link opening it with the interface. Follow that link to verify that it is displayed.

- In the settings of “-gr.koto3″ it is possible to change the format of graphic display. Currently it was “Show objects”. Let us try “Piano roll”. This format highlights the melodic and harmonic structure of the composition whereas the “objects” format is explicit on the size and location of sound-objects.
- Comparing the two images we can guess that “a” contains one instance of A5 and “b” contains two strokes of B5. The «f» sound-object is an out-time object of nil duration containing a single stroke on F2. The «chik» object is also out-time and contains a chord: {C3, F3, C4}.
The main mechanism for creating musical items in this grammar is called substitutions, indicated as SUB on top of the 2nd subgrammar. A substitution rule, when selected, is applied simultaneously to every fragment of the work string. This is made clear by displaying derivations of the string. To this effect, select option “Display production” on the Settings page. Derivation steps will appear on the Trace window:

In the “Non-stop improvize” mode, every step of the substitution is used for the sound output. To this effect, variables are erased and only terminal symbols are played. This produces an effect of the work string “growing” until it collapses as a polyphonic phrase with out-time objects «f» and «chik» playing the bass. The theoretical model behind this process is a (unidimensional) cellular automaton. Listen for example to this performance of “-gr.koto3″:
Importing music
The preceding paragraph was an introduction to the main feature of Bol Processor: creating music with the aid of a grammar, an alphabet and definitions of sound-object prototypes which we will see in greater detail below. This requires a certain amount of expertise in both music composition and the specific task environment of Bol Processor, as shown in the old BP2 reference manual and more recent tutorials.
With BP3 it is possible to proceed in a more simple (yet arguably less creative) manner: import pre-composed music and reuse its fragments to create new variations. This process may be achieved by the automatic conversion of standard musical score in MusicXML format. MusicXML files are downloaded from the Web or exported by score editors such as MuseScore. A description of this method is found on page Importing MusicXML scores along with a discussion of the MusicXML format.
Below is an example of Beethoven’s Fugue in B flat major imported from MusicXML and converted as Bol Processor data — a set of polymetric expressions, read tutorial. It has been played on the PianoTeq physical-model synthesizer using the MIDI file produced by BP3. This example illustrates both the accuracy of this conversion and the level of complexity handled by Bol Processor.
Help messages

- Open the “-gr.NotReich” grammar. At the bottom of the page, click the SHOW HELP ENTRIES button. This will display the grammar with links appearing on reserved words. Click for instance the link on “_volumecont”. A pop-up window will open and display the help at the very location of the reserved word. The help file is still the one used by BP2.9.8. It is being upgraded to BP3.
- At the bottom of the grammar file, two more buttons are displayed: EDIT ‘-se.NotReich’ and EDIT ‘-or.NotReich’. These have been automatically produced because of declarations “-se.NotReich” and “-or.NotReich” on top of the grammar. Click these buttons to edit or create these files.
- You can now produce the “notReich” item, listen to its sound rendering with MIDIjs and display the graphic output as “pianoroll” or “objects”.
Error messages
- Let us now do something wrong to check errors. In “-se.NotReich” change the “Note convention” from ‘0’ (English) to another option such as ‘1’ (French). Click SAVE PARAMETERS, go back to the “-gr.NoteReich” grammar, click SAVE and PRODUCE ITEM(s). Now, neither the “output file” nor the graphics will be visible as the console cannot not create an item due to its misunderstanding of note names. For instance, “G3” is interpreted as a variable and not a note because BP3 takes “G3” as a variable and not a simple note: “G3” should actually have been replaced with its equivalent “sol2” in the French convention.
- PRODUCE ITEM(s) sometimes tells that errors have been detected by the console. They appear on the “error” trace file.
- Try the same procedures with “-gr.trial.mohanam”. It is set for the Indian sargam note convention = 2. After modifying the convention to “French”, the output file will only contain notes “re6” sharing the same name in both conventions. The confusion of note conventions is a frequent source of errors when designing music with the Bol Processor. For this reason, the current setting of this convention is displayed on the Grammar window.
Compile a grammar
- So far, grammars were well-shaped and clicking button COMPILE GRAMMAR would tell that there is no error. Now go to the grammar named “unknown-terminal.bpgr” and click COMPILE GRAMMAR. It tells that errors have been found and the “trace” file explains that it found (at least) an unknown terminal symbol. Indeed, symbols ‘x’ and ‘a’ have not been declared as sound-objects in a related “-ho” alphabet file.
- The COMPILE GRAMMAR procedure renumbers subgrammars and rules. If you are still playing with “unknown-terminal.bpgr”, replace “gram#1[1] S --> A B” with “S --> A B” and click COMPILE GRAMMAR. The numbering “gram#1[1]” will be restored. This takes into account inserting or deleting rules.
- The grammar named “symbols.bpgr” compiles successfully because its has an attached alphabet file containing all its terminal symbols. The alphabet file is named “symbols.bpho” and its declaration in the grammar is “-ho.:symbols.bpho”. This unexpected syntax is a trick for recognizing file types whose names do not start with the standard prefix.
Change the start string

- Musical items are produced by a Bol Processor grammar using by default symbol ‘S’ as a start string of derivations. However it is sometimes interesting to try deriving from another variable with the same grammar, or listen to a polymetric expression. Both these will easily be achieved on the Grammar window.
- An example is the usage of “-gr.Mozart” in which variables represent musical fragments put together in the final item. All variables have been extracted by the interface and displayed as buttons at the bottom of the page (see picture on the right). Clicking a button will produce a derivation of the variable. (This doesn’t yet work.)
- Note however that in this grammar derivations of A1 to B8 wont’t be unique because they are selected randomly. Conversely, derivations from T1 to T176 are unique.
- At the bottom of the page is a field for entering a polymetric expression, for instance {{2,sol3,si3}-,fa5 re5 si4}. This expression may contain variables. Click PRODUCE ITEM to listen to the result or get the output file (depending on the selected output format).
- The “--start” and “-S” command-line options used in these procedures have not yet been implemented.
➡ An example of using “-gr.Mozart” in Improvize mode is discussed on page Mozart’s musical dice game.
Play data

- The Data window (see picture) extracts lines which may be interpreted as musical items in BP notation.
- Each line is associated with two buttons:
- The PLAY button sends a “play” command to the console after storing the data line in a temporary file “…outdata.bpda” saved in the “temp_bolprocessor” folder. The console is asked to process this data as a MIDI file or a Csound score.
- The EXPAND button sends an “expand” command to the console after storing the data line in a temporary file “…outdata.bpda” saved in the “temp_bolprocessor” folder. The result is displayed as text.
Scripts
- Bol Processor BP2.9.8 was fully scriptable in the sense that all commands launched from its menu could be captured as sequences of script instructions to be reproduced at will. This included opening folders and files, modifying text or doing something with the selection.
- A script was executed every evening for about half an hour checking all procedures and tracing changes in output data, in addition to the sound verification.
- This level of automation will not be achieved in the initial version of BP3 because of the disentanglement between the console and its PHP interface. Consequently, many script instructions of BP2 will never be valid in BP3. During the execution of a script they will be ignored.
- 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 Bol Processor BP3...
Type Hope you enjoyed 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!

- In this script, instructions “Show messages OFF”, “Show graphics ON”, “Show messages ON”, “Activate window Scrap” and “Wait for C4 channel 1” will be ignored. The “Play” instruction will expand the polymetric expression - - {2,G4,E4,C4,- C5 - C5 {C5_-,A#4_ _}} and send it to real-time MIDI. The note convention has been set to “English” to recognize “G4”, “E4” etc. as simple notes. The tempo will be default metronome = 60 beats/mn.
- The “Type” instruction displays a line of text (which may contain HTML elements).
- This script calls a subscript named “-sc.trySubscript” in the same folder. Its content is:
Load project -gr.Ames
Csound score ON
Produce items - Here the machine will call grammar “-gr.Ames” and set the output format to “Csound score”.
- Script execution is displayed on a pop-up window (see picture above) listing (in red) commands sent to the console. The second command produces a Csound score, as expected.
- The picture also shows (light blue) buttons for entering script instructions. No typing is required. There is a button labelled CHECK THIS SCRIPT displaying all errors such as a file that wasn’t found.
- Below the script, button LIST ALL SCRIPT INSTRUCTIONS displays all instructions handled by BP2.9.8 indicating which ones are obsolete for BP3 and the ones under development.
Sound-object prototypes
Grammar “-gr.koto3″ uses an alphabet of sound-objects, namely “-ho.abc1″, which is related with a set of sound-object prototypes “-mi.abc1″. The pianoroll display of an item (above in the “Produce items” chapter) already indicated that sound-object “chik” contains a chord of 3 notes. We will now show how these sound-objects can be created or modified.

- Open “-mi.abc1″ (or a copy of it). If the file is correct, below the horizontal line you should see a table containing the names of its sound-object prototypes: a, a’, b, chik, cycle1 etc.
- When opening “-mi.abc1″, a temporary folder has been created in the “temp_bolprocessor” folder. It has a complicated name, for instance “‑mi.abc1_ec02bffaaee23e051fa2afee52e57520_temp” containing the session identifier. If you restart your computer (or your browser) the session number will be different. This folder will therefore become obsolete and a new one will be created with the current session identifier.
- The interface automatically deletes obsolete folders older than 24 hours. Keep pages and tags open as long as you work on a particular set of sound-object prototypes!
- Despite the dependency on session identifiers, no data is ever lost because “-mi.abc1″ is in autosave mode, automatically saved at a period of 30 seconds while working on its sound-object prototypes. This feature is traced by red messages at the top of the page.
- In the table you are offered the option of deleting sound-objects. Try a few DELETE buttons. The good news is that a button named RESTORE ALL DELETED OBJECTS will appear… Click it to undelete sound-objects and return to the initial state.
- You are also offered the option of creating or duplicating sound-objects. In case you do it, don’t forget to add their names to every “-ho” (alphabet) file declaring an affiliation with “-mi.abc1″. The interface makes sure that you are not creating several objects with names currently used or recently deleted.
- Let us now edit an object, for instance “chik”. Click the button bearing that name. Parameters are the same as the ones displayed on BP2.9.8. You can change any parameter and click SAVE THIS PROTOTYPE. In most cases the consistency of values is not checked. We would need a sound output to verify the effect.
- Editing an object includes setting up metrical and topological parameters used by the time-setting algorithm. Read the description of this constraint-solving algorithm taking these parameters into account.
- The PLAY sends a command to the console that will later be executed to play the sound-object or a combination of sound-objects (arranged in a polymetric structure) entered on the form.
Modify MIDI codes in sound-object prototype

- At the bottom of each sound-object prototype page, links EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes display the lists of MIDI instructions and time-stamped bytes that will be sent to the MIDI driver. (First number is actually the number of bytes.)
- ➡ Don’t forget that the “-mi” file is saved in background every 30 seconds (autosave) while modifying sound-object prototypes… To return to the initial version, close the “-mi” tag and restore the “-mi” file from its copy!
- The IMAGE link displays an image of the sound-object prototype along with indications of its topological and metrical properties, much like BP2.9.8’s interface.
- The Play MIDI file link produces a sound output based on MIDI events contained in the sound-object prototype. The “chik” sound-object prototype plays a chord on a stringed instrument lasting for 250 ms. The interface uses MIDIjs Javascript MIDI Player to this effect.
- Notice 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 lever by performance parameters. Therefore it is wise to click SUPPRESS channel pressure and check its effect on EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes. If the change is not immediately visible (it depends on browsers) just reload the pop-up window. Other “continuous” parameters such as “volume control” can be suppressed in a similar manner.
- APPEND AllNotesOff (all channels) may be a useful option to make sure that this object will switch off all pending notes on the sound machine. It broadcasts an instruction on each of the 16 channels.
- The MIDI content of this object can be modified by loading a MIDI file. Click Choose File to select a MIDI file — for instance “test.mid” in the “ctests” folder — then send to upload it. It is not finalized immediately: you can examine EXPLICIT MIDI codes and TIME-STAMPED MIDI bytes of this file before saving it to the sound-object prototype. The “test.mid” example contains no less than 432 bytes because of “Channel pressure” and “Parameter ctrl 7” messages controlling pressure and volume. You can accept the import by clicking SAVE or reject it clicking CANCEL. At present there is no “undo” in case the MIDI sequence has been mistakenly replaced or deleted.
- An important feature is QUANTIZE NoteOns. We are dealing with “striated sound-objects”, thereby meaning that they are designed to be played at a certain tempo. The tempo at which the MIDI content of this object has been captured is generally not the same at which it will be performed, the latter depending on performance parameters. The reference tempo is specified by Tref which is here 1000 ms for a metronome at 60 beats/mn. The MIDI content uploaded from “test.mid” has a duration of 3500 ms, which means 3.5 beats. This duration can be adjusted either in milliseconds or in beat counts. Whatever the duration, it is often convenient to locate NoteOn and NoteOff events on a precise fraction of the beat. An quantization of 1/64 beat is often a good choice. To make things easier we well set it to 1/50 beat, which means 20 ms.
Before clicking QUANTIZE NoteOns, check 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 quantization at 1/50 beats 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.
Csound

Csound is a program for the design and transformation of digitized sounds. Csound and Bol Processsor are similar and complementary in their text-oriented, programming approach, with respective emphasis on sound and musical structures. Their interaction is summarized on the BP2 environment picture.
Note that Csound orchestra files containing sound-production algorithms may be edited on this interface although it is not used by the ‘BP3’ console — nor was it by BP2.9.8. Its name is saved in the Csound orchestra file. Arguments declared in the latter should match those in the former.
A simple orchestra file named “0-default.orc” is supplied in the “csound_resources” folder. It can be used for Csound scores produced by Bol Processor when no Csound orchestra file is specified.
Csound usage by Bol Processor ‘BP3’ is the same as documented in chapter 17 of BP2.9.8 instructions manual. Advanced features are documented in articles Csound checkup and Csound objects.
- Open “-gr.Mozart“in the “ctests” folder.
- Check output option CSOUND file which will (by default) produce a file named “Mozart.sco” in the “my_output” folder. You can change these parameters.
- If Csound is installed and responsive, this status is mentioned on the grammar. Otherwise the machine recommends the installation of Csound (from this site) or to modify the path to Csound — by default “/usr/local/bin/”. Each time a new path is entered, the machine tries to launch “csound --version” and it stops trying once successful.
- Click PRODUCE ITEM(s). A pop-up window will display the successful process. Click Read the output file to read the Csound score on another pop-up window.

In this example, the Csound score has been generated by Bol Processor as a sequence of ‘simple notes’ appearing at the end of each line: “mi5”, “do3”, “do5” etc. To this effect, Bol Processor uses conversion procedures for replacing MIDI events with lines of the score.
If Csound is installed and responsive, it will automatically be called to produce a sound file (in the WAV format) which appears on a player (see picture). Checking the sound output — or rather the validity of the Csound score — is therefore the matter of a single click on PRODUCE ITEM(s).
On each score line, the “1” of “i1” is the value of argument “1”, the leftmost one. The next two arguments are assigned to the on-setting date and duration of the event, measured in beats. Then comes argument “4” assigned to pitch in octave point pitch-class format. Arguments “5” and “6” are for continuous volume control (in range 0…127). Argument “7” may contain the reference of a table for refining these variations. Arguments “8” and “9” used for (continuous) pitchbend control, and argument “10” may contain the reference of a table for refining variations of the pitchbend.

A just-intonation version of Mozart’s musical dice game can be heard on page Just intonation: a general framework.
Csound instrument files
Bol Processor is able to produce a Csound output using scores stored in sound-objects or converted from the MIDI stream. Furthermore, it has a direct control of performance parameters which the Csound orchestra can handle independently on MIDI standard controls (“pitchbend”, “modulation”, “volume” etc.). These parameters are further interpolated by the Csound orchestra, using GEN07 (linear interpolation) or GEN08 (cubic spline) Csound generators. All these are documented in chapter 17 of the BP2.9.8 instructions manual and set up in a “-cs” Csound instrument file as the one shown below.

- Open “-cs.tryCsound” in the “ctests” folder. Pay attention to the fact that this page is in autosave mode (read below): changes in Csound instruments are automatically saved at the rate of two times a minute.
- This Csound instrument file is declared linked to a Csound orchestra file named “tryCsound.orc”. As this file is missing in the “csound_resources” folder, a link is displayed for creating the file. Otherwise it would lead to editing it.
- The text area for Tables does not need more explanations than given in the BP2.9.8 instructions manual. These tables are not used in the production of Csound scores. They are just inserted at the beginning of the score.
- Csound instruments may be associated with MIDI channels. Here, for instance, MIDI messages sent to channel 2 will be converted to instructions sent to instrument 3 “Harpsichord”.
- At the bottom of the page is a list of Csound instruments declared in this “-cs” file. These can be deleted, undeleted and duplicated much in the same way as sound-object prototypes (see above). Clicking the blue button bearing the name of the instrument opens an editor of this instrument.
Editing a Csound instrument

The Csound instrument editor is very similar to that of BP2.9.8’s interface. A detailed presentation may be found in chapter 17 of the BP2.9.8 instructions manual.
- Let us for instance examine instrument Harpsichord in “-cs.tryCsound”. Its index is “3”, thereby meaning that it may be called as _ins(3) or _ins(Harpsichord) on a Bol Processor score.
- Parameters displayed on the “Harpsichord” page are those associated with MIDI controllers. These can be controlled continuously if arguments are given for modifying the start-date and end-date values in a continuous change. The argument under “table” is the reference of an optional tabulated function.
- On the volume parameter, “0”, “64” and “127” (MIDI values) need to be converted to “-24”, “0” and “+24” (Csound values) respectively. Conversion is from a linear to a logarithmic scale.
- The start and end values of the continuously changing volume will be set by arguments “7” and “8” respectively. These are used by an algorithm setting the volume in the associated Csound orchestra, based on GEN07 (linear interpolation) or GEN08 (cubic spline) generators.
- Given three pairs of input/output values, BP2 attempts to define a quadratic mapping between the input and the output. However it may be difficult to match the three values with a monotonous quadratic function… Read page Csound argument mapping for a detailed explanation.
- At the bottom of the page you will find a list of Csound parameters unrelated with MIDI controllers. This is where Bol Processor Csound production may differ radically from MIDI!
- In this instrument, only one additional parameter named “blurb” has been attributed.

These additional parameters may be created, deleted and undeleted in the same way as instruments (see above). The interface makes sure that a new parameter does not bear the same name as an existing one nor a (temporarily) deleted one.
Let us look at the “blurb” parameter (picture on the left). Each parameter has a default value which is not necessarily zero. Values found on Csound scores may be combined additively (ADDval) or multiplicatively (MULTval). This “blurb” parameter sends its start value to argument “9” of the algorithm in the Csound score, and its end value (for continuous variations) to argument “10”.
Using a Csound instrument in a grammar

This usage will be demonstrated in a hypothetic music production simple enough to grasp basic Csound features in its Bol Processor implementation. A complete demo based on a real musical example is found on article Sarasvati vina. We also documented all features of the Csound implementation in articles Csound checkup and Csound objects, showing examples that can be checked with the evaluation version of BP3.
Grammar “-gr.tryCsound” is calling “-cs.tryCsound” and using its instrument “3” (Harpsichord):
S --> _ins(3) _volumecont _volume(127) A4 G4 C5 A5 A4 G4 C5 A5 _volume(0)
The Csound score produced by this grammar is shown below:
; Csound score f1 0 256 10 1 f2 0 256 10 1 0.5 0.3 0.4 t 0.000 60.000 i3 0.000 1.000 440.00 8191.500 8191.500 24.000 21.688 0.000 0.000 0.000 0.000 0.000 ; A4 i3 1.000 1.000 392.00 8191.500 8191.500 21.688 18.431 0.000 0.000 0.000 0.000 0.000 ; G4 i3 2.000 1.000 523.25 8191.500 8191.500 18.431 12.899 0.000 0.000 0.000 0.000 0.000 ; C5 i3 3.000 1.000 880.00 8191.500 8191.500 12.899 -0.031 0.000 0.000 0.000 0.000 0.000 ; A5 i3 4.000 1.000 440.00 8191.500 8191.500 -0.031 -1.179 0.000 0.000 0.000 0.000 0.000 ; A4 i3 5.000 1.000 392.00 8191.500 8191.500 -1.179 -2.794 0.000 0.000 0.000 0.000 0.000 ; G4 i3 6.000 1.000 523.25 8191.500 8191.500 -2.794 -5.547 0.000 0.000 0.000 0.000 0.000 ; C5 i3 7.000 1.000 880.00 8191.500 8191.500 -5.547 -24.000 0.000 0.000 0.000 0.000 0.000 ; A5 s e

- Arguments “5” and “6” display pitchbend start and end values as specified by the instrument. These remain at the default value “8191.5” in the absence of pitchbend instructions.
- Arguments “7” and “8” display start and end values of the volume parameter as expected. The continuous variation is from “+24” to “-24”. This is the result of a mapping between MIDI values in range [0…127] to this instrument’s volume parameter in range [-24…+24] (see picture). This mapping is based on a logarithmic interpolation using a quadratic regression.
- Csound will be able to achieve a continuous variation of this volume parameter. To this effect, it will call its own interpolation scheme specified as GEN07.
- The _volumecont instruction in the beginning of the sequence really means “continuity”. This resolves a discrepancy between MIDI and Csound representation of “musical events”: in the MIDI environment, each event is associated with a time point whereas Csound scores deal with time segments of specific durations. It is up to the Csound orchestra to decide how a parameter should be modified from the on-setting to the off-setting of a segment.
- Arguments “9” and “10” stay at default value “0.000” since the “blurb” parameter is not used.
- Arguments “11” and “12” stay at the default value “0” of the unused modulation parameter.
- Argument “13” stays at the default value “0” of the unused panoramic parameter.
Csound scores produced by “-gr.tryCsound” cannot be played with “BP2test.orc” because their arguments are not matching. They require a different orchestra file named “tryCsound.orc” which we haven’t yet been able to design…
A real musical example using many features of Csound integration in the Bol Processor is a phrase of Carnatic music composed/designed by Srikumar K. Subramanian in 1996. Read the description of this example and listen to its musical rendering (in “just intonation”) below:
Microtonality
In its association with Csound, Bol Processor BP3 is open to microtonality via to the programing of customized scales. Read pages Microtonality and Csound tuning in BP3. Applications to western harmony and to the intonation of ragas in Indian music are exposed in category “Musicology”.
Editing the Timebase

The Timebase is a device for creating a rhythmic pattern that will be superposed to a musical piece produced by Bol Processor in real-time MIDI. The superposition did not work well with BP2.9.8, yet it was working with older versions connected to MIDI via the OMS package. It has not yet been implemented in the ‘BP3’ console. Here we show an editor of the Timebase which is a bit more advanced than on BP2. We also try the superposition by importing Bold Processor’s production as a MIDI file.
- Create a new time base called “try.bptb” in folder “ctests” and open it.
- By default, the time base contains 3 tracks, 2 of which are set up for a simple 4-beat tempo at mm = 60 beats/mn. The third track is empty. Fill it with 4 strokes on key = 100 at a speed ratio 2/1.
- Now listen for the combined 4 tracks (repeated 3 times):
- To understand the structure you can mute some tracks.
- Now click “Choose File” to select a MIDI file, for instance “acceleration.mid”, and click the “send” button to import it.

- You can listen to the imported file and to the combination of this musical piece with the tick pattern:

- The superposition sounds good because the piece has been produced at mm = 60 and it does match a rhythmic pattern of 4 beats. You can try modifying the metronome value on top of the table. In fact, you will get a warning if the metronome setting does not agree with the tempo declared in the imported MIDI file.
- Check for instance this rhythmic cycle on top of “this_song.mid” in the “ctests” folder. You will be told to fix the metronome to 9 beats in 4 seconds as declared in the MIDI file (picture on the right). The matching of beats is perfect:
- This interface makes it possible to add an unlimited number of cycle tracks. (The limit was 3 tracks in BP2.)
- Playing with speed ratios creates complex cycles that can be exploited to control a drum machine if the appropriate channels, key numbers and velocities are set up. Traditional rhythmic structures may also easily be programmed. Examples below:
![]() A 15-beat rhythmic structure called panchamasvari tala in Hindustani music | ![]() Slowly drifting rhythmic patterns |
Tick patterns as polymetric expressions
➡ For experts!
The Timebase page on the PHP interface is a convenient way of superimposing a programmed tick pattern with a production of Bol Processor previously saved as a MIDI file. Another usage of time bases is the control of a MIDI drum machine taking part in the performance. It would make sense to design the drum machine track as part of the performance since polymetric expressions are able to handle superpositions. We will see that even though it is often possible, it remains a tedious task.
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 variable “Drum” to the “-gr.acceleration” grammar:
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 will not work because pattern “Piano” needs to be repeated at the proper tempo instead of being extended in duration… The solution will be 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 named “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 prototypes file “-mi.drum” and define a sound-object named “cycle2”.

- Set it to “cyclic” (see picture on the left).
- Import “drum.mid” to sound-object protype “cycle”.
- Bad news: its duration is 6000 ms instead of the expected 4000 ms…
- Looking at EXPLICIT MIDI codes reveals that the last 2 seconds are a fade-out added by Bol Processor to avoid an abrupt ending.
- Good news: the sound-object prototype editor allows cropping the sound-object by truncating its end. Let us therefore 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 sequence earlier programmed on the Timebase page:
Cropping sound-objects is carefully done. If necessary, the algorithm rewrites “NoteOff” messages deleted by the cropping. - Now the sound-object will be added to the grammar as follows:
-ho.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 “cycle2” sound-object and its related “-mi.drum” prototype file must be declared in the following “-ho.drum” alphabet file:
-mi.drum
The ‘*’ on the second line of the alphabet is an arbitrary symbol declaring a homomorphism — not used here.
*
cycle2
- This method is tedious despite its compliance with the Bol Processor model. Worse, the equivalent polymetric expression may become extremely complex whenever speed ratios or/and beat cycles of all tracks are not equal. In that case it is not displayed at the bottom of the Timebase page.
Setting max computation time
There are many ways to make sure that a grammar does not repeat forever the same process. These are part of the syntax in Bol Processor. For instance, a flag may be decremented each time a rule is applied and may invalidate all rules when it reaches zero.
However, mistakes may happen — and they will happen. Take for instance the following grammar in which a rule rewrites the same string forever:
RND
gram#1[1] S --> X Y
gram#1[2] X --> C4 D4 E4 [Let us at least produce this!]
gram#1[3] Y --> Y [This rule makes the grammar loop forever]

If run without precaution this grammar would apply rule [3] forever. The result would be a blank page until some interruption is called. Fortunately, a limit can be fixed in the settings. For instance 9 seconds.
Note that this grammar will stop but it will nevertheless have created an item “C4 D4 E4” that can be displayed and listened to in MIDI or Csound.
PHP programming tricks
This PHP interface is designed in the most conventional manner, privileging functionality over the aesthetics. The aim of this approach is to deliver a fully operational work environment which software designers will be able to “decode” as a base for the design of a standalone interface in various systems. However, a few special features have been implemented which require explanations because of the painstaking search for documentation that was involved…
Pop-up windows
Pop-up windows should be visible irrespective of security settings on the web browser because they are created by a standard window.open() calls attached to the button.
A typical link activating a pop-up window is this one in “prototype.php”:
echo "<a onclick=\"window.open('".$text_link."','MIDItext','width=300,height=300'); return false;\" href=\"".$text_link."\">EXPLICIT MIDI codes</a>";
The same window.open() code may be put in a “submit” button.
Autosave
The idea of autosave is to mimick the behaviour of Googledocs pages or WordPress posts/pages which are automatically updated at a regular rate. This feature has been implemented for the editing of sound-object prototypes and Csound instruments.
For instance, if you are editing prototypes belonging to “-mi.abc1”, keep in mind that all data is contained in this file. Working on a particular prototype and clicking the SAVE THIS PROTOTYPE button will only update the temporary file — whose path is shown at the top of the page. To finalize the work you should normally return to the -mi.abc1” and click button SAVE ‘-mi.abc1’ INCLUDING ALL CHANGES TO PROTOTYPES. The autosave which is traced on a red line at the top of the page makes it unnecessary.
The same feature has been implemented on the page dealing with Csound instrument files. For instance, “-cs.tryCsound” is automatically saved every 30 seconds while you may be working on the edition of instruments or additional parameters stored in this file.
In practice, autosave is activated by a simple call of Javascript code in files “autosaveObjects.js” or “autosaveInstruments.js”. The command itself is myVar = setInterval(savePost, 30000) in which “30000” stands for 30 seconds. A savePost() function sends POSTs to file “autosaveObjects.php” or “autosaveInstruments.php”. The difficulty lies in figuring out how these POSTs are created in function getData1(). This example will be very useful for programming autosave in various environments such as database editing…
GD graphics and Canvas
The GD graphics library is already bundled with recent distributions of PHP. No installation is required provided that PHP has been compiled with the “gd” option. If you have any doubt, display the “http://localhost/try/bolprocessor/php/phpinfo.php” page on your local server.
An example of using GD instructions is on page “prototype_image.php”. Note that all variables used to build the image have been stored in a temporary file “image.php”. This makes it unnecessary to send hundreds of POST messages to “prototype_image.php”.
Graphic procedures in the console have been implemented in HTML Canvas which is compliant with standard HTML5 and does not require PHP. Each image is saved as a set of javascript instructions allowing its vectorized construction, unlike GD graphics which produces a PNG image. The Canvas script contains width and height values used for clipping the image. These are read by the PHP script on “produce.php” for setting up dimensions of the pop-up window that will contain the image.