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.

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 --rtmidi or --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. rtMIDI remains false, which makes MakeSound() write the score (cswrite) instead of sending MIDI events. Options --rtmidi and --csoundrt cannot be used together. --csoundout can: the same score is then written to a file as well, which is useful for testing (see “Debugging” below). At the end of the arguments, CsRTOpen() is called.

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

When stop() finds the pause file, it sets PausePlay. CsRTFlush() then:

  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 of STOP or PANIC);
  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).

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

Leave a Reply

Your email address will not be published. Required fields are marked *

« Translate