Basic information about DirectCsound, a realtime oriented version of Csound

By Gabriel Maldonado

Features of this version of Csound

General

Command line arguments

Examples of command-line calls of DirectCsound

Hints

Features of this version of Csound

Here is a list of the features of DirectCsound, following the versions order.
VERSION
FEATURES
release 1.0
  1. Allows realtime midi input from Windows standard MIDI devices 
  2. Allows to define the number of output WAVE buffers 
  3. Allows to define virtual console of up to 2050 lines of text output (obviously through a scrolling window) 
  4. Recognizes all installed Windows MIDI input and WAVE output devices and, if these are more than one, it prompts the user for the device number desired. 
  5. Includes my "soundin2" new UG allowing interpolated and continuous pitch-shift reading of a soundfile. This UG also takes care of in/out sr difference during the processing (see soundin2.txt and soundin2.src files). 
  6. Includes all official John Fitch et al. 3.46 UGs, upgrades and fixes (see UG_ver34.txt and UG_ver35.txt files) 
  7. Includes all Robin Whittle's UGRW1 & UGRW2 UGs (see ugrw1.txt and ugrw2.txt files). 
  8. Allows full 16 bit stereo output up to 44100 Hz in realtime. 
Release 1.5
  1. More than 50% improved processing speed (more poliphony!). 
  2. arbitrary sr allowed from 5000 hz to 44100 hz for soundcards that support it (such as SB16 and AWE32 family). 
  3. drastically reduced realtime latency delay by reducing buffer length and consequently more interactive realtime operations when using rounded sr and kr (such as for example sr=32000 or sr=40000 and kr=100) 
  4. executable file length considerably reduced. 
  5. New UGs: midi realtime control with up to 21 bit precision ("midic7", "midic14" and "midic21" UGs). These new UGs also support optional table indexing 
  6. New UGs: "mirror" and "wrap" for clipping and modeling krate or audio signal in several ways. 
  7. new flag for suppressing all console text output for better realtime performance. 
  8. new flag for not waiting a keypress on exit 
  9. flag "-B" is automatically calculated on "-b" value so it is now redundant. 
  10. some bug fixing (such as the read-only attribute in output wave files when processing non-realtime operations). 
  11. new flag for graphic display of tables with Wcshell by Riccardo Bianchini (graphic of tables is saved in binary format). 
Release 1.71
  1. Realtime MIDI OUT UGs: "ion" "ioff" "iondur" "iondur2" "moscil" "kon" "ioutc" "koutc" "ioutc14" "koutc14" "ioutpb" "koutpb" "ioutat" "koutat" "ioutpc" "koutpc" "ioutpat" "koutpat" "mclock" "mrtmsg". 


    All these UGs can run in parallel with MIDI IN and WAVE OUT 

  2. MIDI-activated note-duration extension capabilities by means of new "xtratim" opcode. New "release" opcode allows the user to make complex ADSR envelopes if uses "release" in pair with "xtratim" 
  3. Optional replacing of WAVE OUT operations with a timing function during realtime performances. This enhances timing precision when using MIDI OUT UGs, but suppresses AUDIO out. This also hugely reduces program overhead, freeing the most part of CPU's resources when Csound is running, and enhances multitasking (flag '-Y'). 
  4. Optional yielding control to Windows during realtime DAC performance. This reduces program overhead, freeing a big part of CPU's resources when Csound is running, and enhances multitasking (flag '-*'). 
  5. some bug fixing and code enhancement 
  6. now dialog boxes appear when a WAVE or MIDI device error incurr. 
  7. In realtime operation '-o' and '-M' are now redundant when using '-q' and '-K' flags. 
  8. '-q' (WAVE OUT) '-K' (MIDI IN) and new '-Q' (MIDI OUT) flags can handle optional numeric arguments. If these numeric arguments are not present, console messages appear. These messages ask the user to type in the corresponding device id. 
  9. Now, when using -O flag, console text output suppression is active after orchestra and score compilation, allowing to view syntax errors. 
  10. New UGs included in  John Fitch version 3.46 (PVOC fixed, HRTF fixed, FOG, DISKIN and MIDI pitch-bend related). 
Release 1.72
  1. Command line can now be included in a file ('-/' flag). Very useful using Win95 long names, when command line is more long than 138 characters allowed by DOS. 
  2. ftlen2() function now can return non-power-of-two length of deferred tables created with GEN1. 
Release 1.731
  1. New MIDI IN controller UGs. The same as midicXX opcodes but now they can be activated by a score i statement without Csound crashes. These UGs are : ictrl7, ctrl7, ictrl14, ctrl14, ictrl21, ctrl21. A new argument allow the user to define the MIDI channel apart from the instrument number. 
  2. Initialization of controllers now can be set to any value (it can different from the minimum value set in midicXX and ctrlXX. Opcodes initc7, initc14, initc21). 
  3. LOSCIL2 opcode uses 16-bit integer function table (see GEN 22) for storing samples. Very useful for LONG samples. 
  4. FOF3 opcode, the same as fof2, but reads 16-bit integer samples from tables generated by GEN22. 
  5. GEN22 is identical to GEN 01 except that stores 16-bit samples in RAM keeping 16-bit integer format. This halves RAM need. Very useful for LONG samples. 
Release 1.8 
(sept. 97)
  1. MME WAVE OUT in parallel with FILE OUT. You can now record directly to hard disk in digital domain your realtime performance! (You must have a fast hard disk driver to use this feature). 
  2. Now, when flag '*' (yielding control to system for better multitasking) is set, Csound Win32 process is set to Realtime priority class. This make Csound to have precedence over most other concurrent processes, enhaching realtime performance. 
  3. Resonant lowpass filter (lpres) and layering filters opcodes (tonex, atonex, lpresx) which can serialize more filters, giving a more sharp cutoff and increasing performance speed and code readability. 
  4. fof3 opcode now lineary interpolates audio samples to produce a very better sound quality. 
  5. sample table related functions (GEN1 and GEN22): ftlen2(), nsamp() and ftsr(). 
  6. printk2 (for printing realtime sliders changes) 
  7. general purpose physical modeling algorythms are now implemented as opcodes ("physic1" and "physic2") 
  8. Plug-in DLL library of Perry Cook toolkit with several physical model algorythms, plus support for external opcode libraries (coded by Michael Gogins). 
  9. several bug fixes remarkably in midi IN and OUT (for example midi channels now are 1-16 instead of 0-15; now MIDI OUT timing should be OK) 
RTsound 1.9 
(jan. 98)
  1. RTsound now allows realtime WAVE IN operations on Win95 (of course in parallel with WAVE OUT). Plug your sound card to an external mono or stereo sound source (for example a couple of microphones), and use the huge Csound power to transform it! 
  2. All opcodes of standard 3.47 version now implemented. 
  3. Now you can use uppercase letters and "_"  (underscore character) for variable names, hugely improving orchestra readability. 
  4. Character "\" can be used to split an orchestra line, and can be followed by a comment ";" 
  5. New MIDI OUT opcodes: "midiin", "midiout", "kon2", "nrpn", "mdelay" 
  6. New filter opcodes: variant resonant lowpass filter "vlpres" 
  7. New oscillator algorithms allow more precise frequency control ("posc" ), and can vary table read margins at k-rate ("lposc","lposcint") 
  8. short exponential segments now work well at a-rate with opcode "aexpseg" 
  9. New MIDI IN opcodes ("midiin") and fast bank-of-sliders management with "slider8", "slider16", "slider8f", "slider16f", "islider8", "islider16" opcodes 
  10. fast power of two function "powoftwo" 
RTsound 1.901 (feb.98)
  1. '-L' flag now operates with realtime console keyboard input (only). 
  2. "powoftwo()" function now allows negative values (see op_manual.txt) 
  3. "logbtwo()" function (see op_manual.txt) added. 
RTsound 1.902 (feb.98)
  1. "intrpol" "kntrpol" "antrpol" opcodes 
  2. "GEN 23" function table generator 
  3. midifile timing bug fixed 
RTsound 1.903 (mar.98)
  1. "Xslider32X" and "Xslider64X" opcodes 
  2. removed all standard MIDI control handling except than sustain pedal (contr.N.64) so up to 127 controllers for each MIDI channel are avalaible for custom realtime control. 
DirectCsound Version 2.0 (June 98)
  1. Implements Win32 DirectSound routines in audio output. This drastically reduces latency delay!! At last it is possible to play Csound with a piano-like style as it would be a hardware synthesizer. Fast Pentium II processors are recommended. 
  2. All opcodes and features of standard 3.482 version now implemented 
  3. Covers all opcodes and features of RTsound 1.9xx 
  4. "flanger" opcode 
  5. "intrpol", "kntrpol" and "antrpol"  opcodes interpolate two input signals 
  6. "logbtwo(x)"  the inverse function of powoftwo 
  7. "slider32", "slider64", "slider32f", "slider64f", "slider16b14", "slider32b14" opcodes 
  8. "GEN23" gen-function reads numeric values from an external ascii file 
  9. "GEN24" gen-function reads numeric values from another allocated unction-table and rescales them according to the max and min values given by the user 
DirectCsound Version 2.1 (September 98)
  1. Now Csound language allows subroutine calls! (opcodes "icall" "dicall" "micall" "dmicall" "kargc" "kargt" "argc" "argt" "artrnc" "artrnt" "krtrnc" "krtrnt") 
  2. better DirectX realtime audio with flag -+* 
  3. new opcodes: "foscili2" "cpstmid" 
  4. some bugs fixed 

General

This version of csound does not have an IDE interface, so, to run it, you must type a command-line with several arguments from a DOS window (alternatively you can write a batch file or a shell program to run DirectCsound. A good shell program for this Csound version is WCshell by Riccardo Bianchini, written in Visual Basic. Another realtime oriented shell is my program VMCI, available at the url: ftp://musart.dist.unige.it/CSOUND/win95/).

Note that in this version of Csound command line arguments are not optional, if you don't type them correctly DirectCsound will show an error message! SEE below for some command line example.

If you already know standard Csound, let's read all the additional features of this version

If you don't know Csound you must study the main manual at first.

Command line arguments

FLAG

ARGUM

DESCRIPTION

-+K 

 <num> Enable MIDI IN.
<num> = MIDI IN device id number. 
<num> is optional, if you omit it, a list of available MIDI IN devices will be displayed, then you can choose one of them by typing the corresponding number to the console. If this flag is used, don't use the standard flag -Msbmidi. 

-+q 

 <num> Enable MME WAVE OUT.
<num> = WAVE OUT device id number. 
<num> optional, if you omit it, a list of available MME WAVE OUTdevices will be displayed, then you can choose one of them by typing the corresponding number to the console. This flag enables the old MME  WAVE OUT. Don't use this flag  together with -+X (DirectX audio). If this flag is used, don't use the standard flag -odevaudio. When using '-o<FILENAME>' together with '-+q' flag, both realtime audio and FILE output are enabled in parallel. 

-+p 

 <num> Set the buffer number in MME WAVE OUT.
<num> is optional. default=4, maximum=40. 
The number of buffers, togheter with the buffer length (flag -b<num>), must be choosen accurately, considering that, when increasing the buffer, the latency delay increases too, whereas when decreasing the buffer, the risk of pop and click due to buffer underruns increases. 

-+j 

 <num> Console virtual text rows number.
It is possible to define the number of rows of the console (max 2000) by using this flag. 

-+J 

 <num> Console virtual text columns number. 

-+O 

   (uppercase letter) Suppress all printf for better realtime performance.
Using this flag is better than using '-m0' because '-m0' still leaves some message output to the console.  I suggest to use both -+O and -m0 at the same time for the best realtime performance. Warning! Use '-+O' only when your orc/sco files are fully tested, because the error messages are suppressed too. 

-+e 

   Allow any output sample rate (for cards that support this feature).
When you use a non-standard sr in realtime (for example 40000), a message will inform you that this sampling frequency is not allowed by the card. Some cards can handle all the sr frequency (for example the Sound Blaster cards) within a range continuously (for example from 8000 to 44100). So you can use these frequencies without any problem by setting this flag. 

-+y 

   Don't wait for keypress on exit.
Useful for batch processing. 

-+Q 

 <num> Enable MIDI OUT.
<num> = MIDI OUT device id number. <num> is optional, if you omit it, a list of available MIDI OUT devices will be displayed, then you can choose one of them by typing the corresponding number to the console. 

-+Y 

   Disable WAVE OUT (for better MIDI OUT timing performances).
When using MIDI OUT oriented orc/sco pairs, disabling WAVE OUT will improve the timing of MIDI OUT flow. 

-+* 

   Yields control to system until DAC buffer is half-empty, for better multitasking.
In some cases this flag enhanches the realtime performance, and, above all, allow to use other graphic programs concurrently with Csound in realtime, without interruptions of the sound flow. This flag will slow all other application, because set Csound process to a higher priority. It can be used both with MME (-+q) and DirectX (-+X) drivers. 

-+/ 

 <filename> Csound command line is intended to be included in a text file.
The command file must contain the flag as well as the other arguments in the same syntax of csound command line. Carriage returns inside the command file are ignored. 

-+X 

 <num> Enable DirectSound routines for low latency delay of audio output. 
<num> optional, if you omit it, a list of available DirectX audio devices will be displayed, then you can choose one of them by typing the corresponding number to the console. Don't use this flag  together with -+p and -+q flags (which enable old MME WAVE OUT). Also, don't use the standard flag -odevaudio with this flag. When using '-o <FILENAME>' together with '-+X' flag, both realtime audio and FILE output are enabled in parallel. 

Examples of command-line calls of DirectCsound

The following command-line invokes realtime MIDI performance of Csound with the DirectSound routines. The console messages are suppressed (-+O and -m0 flags), it is asked to the user the midi input port number to be used (-K flag) and the DirectSound device number (-X flags). The buffer length is set to 100 samples. 

csound.exe -+O -m0 -+X -+K -b100 miditest.orc miditest.sco
Same as the above, but with -+* flag to enhance realtime DirectX audio multitasking (in some cases this flag can make realtime performance worse. Experiment!). 

csound.exe -+O -m0 -+X -+K -b100 -+* miditest.orc miditest.sco
The following command-line invokes realtime midi performance of Csound with pedal treshold of 99, 12 wave out buffers of 882 bytes each, and prompts the user to input the MIDI IN and MME WAVE OUT device numbers. An audible delay is present, due to  the latency of the MME driver: 

csound.exe -P99 -+p12 -b882 -+K -+q miditest.orc miditest.sco
same as above but with all displays suppressed ("-O" and "-m0" flags. Use this feature only when your orc and sco are fully tested!): 

csound.exe -+O -m0 -P99 -+p12 -b882 -+K -+q miditest.orc miditest.sco
same as above but with display enabled, a 1000 rows virtual console, midi device number 4 (flag '-+K') and wave out device number 0 (flag '-+q'): 

csound.exe -+j1000 -+K4 -+q0 -P99 -p12 -b882 miditest.orc miditest.sco
some as above but with '-+*' flag to enhance Windows multitasking: 

csound.exe -+* -+j1000 -+K4 -+q0 -P99 -+p12 -b882 miditest.orc miditest.sco
allows arbitrary sample rate (e.g.other than 1025/22050/44100) with '-e' flag and MME WAVE OUT (Note the reduced -+p and -b values when using "rounded" sr and kr values; these values are good with my Pentium133 with a sr=40000 and kr=400): 

csound.exe -+e -+O -m0 -P99 -+p4 -b100 -q -K miditest.orc miditest.sco
allows MIDI OUT operations with device num.5 (flag '-Q') in parallel with WAVE OUT: 

csound.exe -+e -P99 -+j2000 -+Q5 -+q -+p4 -+K4 -b100 midiout.orc midiout.sco
allows MIDI OUT operations with device num.5 (flag '-Q') and suppresses WAVE OUT for better MIDI OUT timing (flag '-Y'): 

csound.exe -+e -+Y -P99 -+j2000 -+Q5 -+q -+K4 midiout.orc midiout.sco
calls csound by command line contained in file 'cl.txt': 

csound.exe -+/cl.txt
enables realtime WAVE IN operation (flag '-i'without arguments) in parallel with WAVE OUT (flag '-+q') and asks to the user the number of Multimedia-Windows devices: 

csound.exe -+p12 -b882 -+q -i

Hints

There are two ways to start realtime audio output sessions: using DirectSound or old MME WAVE OUT. Don't use both the flags at the same time! 

To use DirectSound you have to set the -+X flag together with -b flag. The buffer length determines how quick the response to your realtime actions is. With my Pentium 133 a value of -b100 is the minimum possible value: below that sample-flow interruptions will occurr (i.e. pop and clics will be heard). However, with other computers it should be possible to reduce this value to allow a faster note response (curiosly, sometimes faster computers need a bigger value as in the case of my new Pentium II 400 MHz, which needs at least a -b200 value). 
DirectSound is very sensitive to everything is happening in your computer, so during realtime performances you MUST SUPPRESS all console messages by means of -+O and -m0 flags otherwise sound flow interruption will occurr. You can type the -X flag with a number identifying the DirectSound device to be activated. If you type it without a number, a list of installed DirectSound devices will be shown in the console window asking the user to type a number.
When DirectSound is not used, finding the optimum values for "-b" and "-+p" flags (which enable the old MME WAVE OUT driver) requires some experimentation: more buffer length means more latency delay but also more safety from dropouts and sound interruptions (flag "-B" is now obsolete, don't use it). 
Now it is possible  to reduce buffer length and delay by using '-+e' flag and 'rounded' sr and kr. 
Notice that sometimes a smaller buffer length can handle sound flow better than a larger. Only experimentation can lead you toward optimal '-b' values. 

However the minimum latency delay can be allowed only when using DirectX (+X flag) instead of old MME driver.
When DirectSound is not used (i.e. when using old MME drivers), optimum "-b" and "-+p" flag values need to be changed with different audio and k rates. These changes are not linear and not intuitive. So experiment!
It is suggested to set "-b" value to integer multiples or sub-multiples of kr. This tip sometime can help to reduce latency, sometime not. Again, experiment to find optimum values.
When old MME WAVE OUT driver is used, "-b" and "-+p" flag values can be reduced considerably by using "rounded" ar and kr values (for example ar=32000 and kr=320; ar=40000 and kr=400 and so on) together with "-e" flag (until now this feature is tested only with a SB16 ASP and with an AWE32 card. I don't know if other cards support it).
Reducing "-b" and "-+p" flag values means reducing latency delay and so a more interactive realtime playing.
"-+Q" flag allows parallel MIDI OUT and DAC performance. Unfortunately the realtime timing implemented in Csound is completely managed by DAC buffer sample flow. So MIDI OUT operations can present some time irregularities. These irregularities can be fully eliminated when suppressing DAC operations themselves ('-+Y' flag).
"-+Y" flag suppresses DAC operations. This enhances timing of midi out operations when used in conjunction with "-+Q" flag. It is recommended to use "-+Y" with low krates (max. kr=1000). As in Win95 maximum timer resolution is 1/1000 of second, unpredictable results can occurr when using it at krates greater than 1000. 
Also it is very important to set only kr values in which the following division:
1000/kr 
produces integer results (some example: kr = 10; 20; 50; 100; 125; 200; 250 etc.) because Win95 timer only handles integer periods in milliseconds. If you use a kr value that produces a non integer result in the above formula Csound seems to run normally but times will be not reliable.
With my computer I work very well with a value of kr=200. Maybe with slower computers a lower value works better. Experiment!

I recommend to use kr=200 or less because with values greater than 200 increases the overhead affecting the entire system and do not give a notable precision improvement. A time resoultion of 1/200 of sec is enough precise for almost all MIDI application. You must respect sr/kr/ksmps ratio even if sr value is meaningless when using "-Y" flag, or an error message will stop the performance.
'-+*' flag compells Csound to yield control to system until audio output buffer content passes a certain threshold. Below this threshold Csound continues processing, while over this threshold Csound yields control to Windows. This gives a big enhanchement in multitasking processes. Enabling this option reduces polyphony a bit when using short buffer space. So the user should increase the number ('-+p' flag) and the length ('-b' flag) of buffers when setting '-+*' flag. Experiment to find best values.
For best realtime performance, it is (obviously) better: 
  1. reduce the number of concurrent applications running 
  2. not moving neither resizing or closing windows during all realtime session. 
'-+O' flag suppresses all text output during the performance time. Using only '-m0' flag, some text messages are still sent to the console. I suggest to use '-m0' and '-+O' flag together for maximum performance speed.
'xtratim' and 'release' opcodes (as well as 'linenr') don't operate correctly when using -t flag.
When using ctrlXX and midicXX opcodes you must be sure the MIDI IN flag (-K and/or -Msbmidi) is activated, or Csound will crash!
When using realtime AUDIO input you must set the -i flag without argument, or followed by a number which represent the wave-in port number recognized by Win95. (ex. -i0). Notice that DirectX realtime input is not implemented yet, so you must use the old MME driver.
When using parallel WAVE out and FILE out, you must set -o flag followed by the output file name (which must have a name different than "devaudio" or "dac" obviously), toghether with the -+q flag (when using MME) or -+X flag (when using DirectX).