Basic information about DirectCsound

By Gabriel Maldonado
http://web.tiscalinet.it/G-Maldonado


General (IMPORTANT! Read this first if you are trying DirectCsound for the first time!)

History of changes and new features of this version of Csound

Command line arguments

Examples of command-line calls of DirectCsound

Hints

Acknowledgements


General

To run current version of DirectCsound is sufficient to double-click the program icon. See the GUI section for more information.
Alternatively you can write a batch file or use a special program to run DirectCsound. A realtime-oriented IDE for DirectCsound is my program VMCI, available at the url: http://web.tiscalinet.it/G-Maldonado).

(Previous versions of Csound didn't have an IDE interface, so, to run them, you must type a command-line with several arguments from a DOS window. Note that command line arguments were not optional in older versions of Csound, whereas now it is possible to type them after running DirectCsound executable).

In version 2.5 a unified orc/sco file feature was implemented, so you can run DirectCsound simply dragging the .csd file to the executable file icon. In this case the command line flags are embedded into the .csd file, so the only command line arguments are the executable name (i.e. csound.exe) and the .csd file itself.

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. You can get it at the following urls:

http://hem.passagen.se/rasmuse/Csound.htm (WinHelp format);

http://www.lakewoodsound.com/csound (PDF format);

Furthermore, even if you perfectly know Csound, you have to study the present document too, as well as the the DirectCsound manual addendum, because several things are different, especially regarding the command-line arguments and the new spatialization-related opcode.


History of changes

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 GEN01 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 
DirectCsound
Version 2.5

(January 99)

  1. This version is synchronized with canonical Csound 3.494 (all opcodes, macros, score math, etc.)
  2. unified orc/sco files are now enabled (with a little modification with respect of that of canonical version). These files can contain the execution flags too. To run an unified file simply drag it to the csound.exe file icon (the file msut have .csd extension). These files use the M.Gogins syntax: see test.csd as an example.
  3. New opcodes: "fout", "vincr", "clear" and "fold"
  4. Midi Program Change messages and Pitch Bend are now implemented in realtime.
  5. Operator "^" allows power raising in score macro arithmetic.
  6. Many bugs fixed.
  7. Opcodes renamed to stay synchronized with canonical version:
    kon -> midion
    kon2 -> midion2
    physc1 -> wguide1
    physic2 -> wguide2
    iwrap -> wrap
    imirror -> mirror
    trig -> trigger
DirectCsound
Version 2.6

(February 99)
  1. new score opcodes: { } (nested loops), F (score table creation)
  2. new score macro arithmetic operators: T (score table access), R (random numbers), ^ (power), % (modulus)
  3. Nested macros. The syntax of macros with arguments has changed a bit : now comma character must be used in order to separate arguments instead of '#' character .
  4. During each csound session a file named orc.srt containing orchestra macro expansions is created, in order to find bugs when using macros.
  5. New orc opcodes: resony
  6. some bugs fixed
DirectCsound
Version 2.70

(March 99)
  1. syncronized with canonical Csound ver. 3.52
  2. String p-field allowed in score with reference to the following opcodes:
    adsyn, pvoc, soundin, diskin, lpread, convolve etc. can now receive string argument by a note in score
  3. no more noises or repeats of last chunk of samples at the end of a realtime session.
  4. some bug fixed
DirectCsound
Version 2.80

(July 99)
  1. New opcodes: foutk, fouti, foutir, fiopen, fin, fink, fini to handle binary and text files in/out.
DirectCsound
Version 2.90

(September 99)
  1. Synchronized with standard version 3.58
  2. Gen functions now can generate tables having non-power-of-two length, by giving a negative length value.
  3. poscil now can accept negative frequency values, and a-rate values both for amplitude and frequency, so both AM and FM are allowed using poscil. Also, differently by oscil family, they allow non-power-of-two length tables.
  4. tab and tabw opcodes, faster than table and tablew, accept non-power-of-two length tables.
  5. phasor now supports a much more precise phase generation, as phase is stored into a double internal variable instad than float (like poscil family). This removes some imprecision  and distorsion when writing and reading long tables.
  6. Added latest opcodes of Peter Neubaecker and Jens Groh (though must be tested).
  7. wguide1 and wguide2 now accept both k and a-rate arguments for frequency, in order to eliminate distorsion in vibratos and glissandos.
DirectCsound
Version 3.0

(October 99)
  1. Windows DirectSoundCapture support (-+C flag). Low latency audio input (for those audio cards that support it in native mode).
  2. Windows DirectSound support of secondary buffers (-+S flag. This makes DirectCsound compatible with more Windows platforms).
  3. Support realtime three-dimensional audio (surround audio with some audio cards): Microsoft's DirectSound3D and Creative's EAX 2.0
  4. Windows DirectSound3D support.   New opcodes: Init3dAudio, Out3d, DsListenerPosition, DsListenerOrientation, DsListenerRolloffFactor, DsListenerDistanceFactor, DsListenerSetAll, DsMode, DsPosition, DsMinDistance, DsMaxDistance, DsConeAngles, DsConeOrientation, DsConeOutsideVolume, DsSetAll, DsEaxSetDeferredFlag, DsCommitDeferredSettings.
  5. Creative's EAX 2.0 support: New opocodes: EaxListenerEnvironment, EaxListenerEnvSize, EaxListenerEnvDiffusion, EaxListenerRoom, EaxListenerRoomHF, EaxListenerDecayTime, EaxListenerDecayTimeHfRatio, EaxListenerReflections, EaxListenerReflectionsDelay, EaxListenerReverb, EaxListenerReverbDelay, EaxListenerRoomRolloff, EaxListenerAirAbsorption, EaxListenerFlags, EaxListenerAll, EaxSourceDirect, EaxSourceDirectHF, EaxSourceRoom, EaxSourceRoomHF, EaxSourceObstruction, EaxSourceObstructionRatio, EaxSourceOcclusion, EaxSourceOcclusionRatio, EaxSourceOcclusionRoomRatio, EaxSourceRoomRolloff, EaxSourceAirAbsorption, EaxSourceOutsideVolumeHF, EaxSourceFlags, EaxsourceAll
  6. Termination action in response of a MIDI 0xF5 message (which at present time is not used for any other purpose). So to terminate a realtime session of DirectCsound is sufficient to send a 0xF5 byte via MIDI. This help with shells, and makes useless to focus Csound console and to press Ctrl-C. VMCI Plus 2.01 supports this feature.

DirectCsound
Version 3.01

(October 99)
  1. Support for orchestra without score (for realtime sessions). When no score file name is given as command line argument DirectCsound automatically creates a dummy score containing "f0 86400" that allows 24 hours of realtime performance.
  2. Rasmus Ekman's schedkwhen and new  Jens Groh and Peter Neubäcker opocodes nalp and phasorbank. (All these opcodes are not tested).
  3. .csd file bug fixed
  4. other minor bugs fixed.
DirectCsound
Version 3.04

(December 99)
  1. Sinchronized to standard version 4.01
  2. Several bug fixes mainly regarding DirectX, DirectSound3D and EAX 2.0
  3. Available a version compiled with the ultra-fast INTEL compiler for Pentium II and faster processors
  4. New opcodes: loopseg and lpshold
DirectCsound
Version 4.00

(January 2000)
  1. DirectCsound 4.0 is a pure Win32 program, while previous versions were console-based programs
  2. It now provides a GUI interface
  3. Display and hard-disk recording can be suppressed/activated during the performances
  4. Command line arguments can be typed directly in the corresponding dialog box when the executable is run without arguments
  5. Performance sessions can be terminated without exiting from the main program.
  6. It is possible to drag/drop a .csd file to the main window of DirectCsound  to run it directly.
DirectCsound
Version 4.5

(March 2000)
  1. SoundFont2 support: sfload, sfplist, sfilist, sfpassign, sfpreset, sfplay, sfplaym, sfinstr and sfinstrm opcodes
  2. Random generators: random, randomi and randomh opcodes
  3. User-defined random distributions: GEN40, GEN41, GEN42 subroutines, Dusrnd, urd, Cusrnd opcodes
  4. "Natural" and "analog" vibrato generators: vibrato, vibr
  5. "Analogizing" opcodes: jitter, jitter2
  6. "edit orchestra" and "edit score" buttons on the GUI interface
  7. many bug fixes
DirectCsound
Version 4.65

(June 2000)
  1. Sequence-related opcodes: seqtime and trigseq
  2. Random curve opcodes: jspline and rspline
  3. Tables of vectors read/write access: vtable, vtab, vtablew, vtabw
  4. Common musical converters: octave( ), semitone( ), cent( ), db( ).
  5. new version of SoundFont2 support, hugely fixed now it should operate OK with most sf2 files. Cubic interpolation now available.
  6. Synchronized to canonical version 4.05
  7. Many bugs fixed
  8. Both GUI and console versions now available
DirectCsound
Version 5.00

(January 2001)
  1. BITMAP IMAGES can be used to generate scalar and vectorial control signals: opcodes bmopen, bmtable, bmtablei, bmoscil, bmoscili, rgb2hsvl, rgb2hsvl_i, bmscan and bmscani
  2. FRACTALS: Mandelbrot set can be used to generate control signal, opocde mandel
  3. VECTORIAL OPERATORS: now it is possible to apply mathematical operations to vectorial signals: opcodes vadd, vmult, vpow, vexp, vaddv, vsubv, vmultv, vdivv, vpowv, vexpv, vcopy, vmap, vlimit, vwrap, vmirror
  4. VECTORIAL SIGNAL GENERATORS: opcodes vlinseg, vexpseg, vrandh, vrandi
  5. VECTORIAL MODIFIERS: opcodes vport, vecdelay
  6. Control rate variable delay: opcode vdelayk
  7. CELLULAR AUTOMATA: vcella opcode generates a vectorial signal based on CA algorithms.
  8. Additive synthesis oscillator bank: adsynt2 opcode is designed to receive vectorial  control signals.
  9. GLISSANDO GENERATORS: opcodes lineto and tlineto
  10. TRIGGER METRONOME: opcode metro
  11. MICRO TUNING: opcodes cpstun and cpstuni
  12. Synchronized with canonical Csound version 4.10
  13. 32 bit and 64 bit floating-point versions provided, both in console and GUI fashion.
  14. Many bugs fixed (other ones could arise, however, due to the radical changes of last canonical versions)
DirectCsound
Version 5.10

(March 2001)
  1. DirectCsound implements GUI-widget opcodes to control synthesis parameters in realtime. Such opcodes have been written using the ultra-fast and multi-platform FLTK library. Both console and windows version support such opcodes. The introduction of FLTK (and, in the near future, of OpenGL) opens a new era for Csound, that will support both graphic and sound.
  2. GUI containers: FLpanel, FLpanel_end, FLscroll, FLscroll_end, FLtabs, FLtabs_end, FLgroup, FLgroup_end, FLpack, FLpack_end
  3. GUI valuators: FLslider, FLknob, FLroller, FLtext, FLjoy, FLcount
  4. GUI widgets: FLbutton, FLbutBank, FLbox, FLvalue, FLprintk, FLprintk2
  5. Opcodes that modify widget apparence: FLcolor, FLlabel, FLsetVal_i, FLsetVal, FLsetColor, FLsetColor2, FLsetTextSize, FLsetTextColor, FLsetFont, FLsetTextType, FLsetText, FLsetSize, FLsetPosition, FLhide, FLshow, FLsetBox, FLsetAlign
  6. General widget-related opcodes and snaphsot support: FLrun, FLsetsnap, FLgetsnap, FLsavesnap, FLloadsnap
  7. Synchronized with canonical Csound version 4.12
  8. Some bugs fixed



Command line arguments

FLAG 

ARGUM

DESCRIPTION 

-+S 

<num> Enable DirectSound secondary buffer writing. 
<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) or -+X flag. Also, don't use the standard flag -odevaudio with this flag. When using '-o <FILENAME>' together with '-+S' flag, both realtime audio and FILE output are enabled in parallel. 

IMPORTANT
! Notice that some audio card (such as old SoundBlasters) automatically convert sound to 8-bit when using secondary buffers, so audio quality can be ugly. Also latency delay can be very high. Use primary buffer in these cases.

-+X 

<num> Enable DirectSound primary buffer writing for low-latency 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) or -+S flag. 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. 

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

-+C 

<num> Enable DirectSoundCapture routines for low-latency audio input. 
<num> optional, if you omit it, a list of available DirectSoundCaputure 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 -i flag (which enable old MME WAVE OUT). Also, don't use the standard flag -iadc with this flag.

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

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




 
 

Examples of command-line calls of DirectCsound

The following command-line invokes a unified file session. (flags details are set internally to the .csd file).

csound.exe   test.csd

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 -b200 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

some as above but with '-+*' flag to enhance Windows multitasking: 

csound.exe -+* -+K -+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 try 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 (for example, when using audio IN and audio OUT at the same time), "-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, because the fullness of audio buffer cannot be predicted at each moment. These irregularities are reduced when audio buffer length is very short. At last, 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 noticiable 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 could reduce polyphony a bit when using short buffer space.  In this case, 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 recommend 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, otherwise 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 WAVE out and FILE out in parallel, 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).
Unified file directive syntax (DirectCsound, as well as the canonical csound version, now partially implements Micael Gogins' AXCsound structured data files):

The following example is a "csd" text file template. The format of .csd files follows the same principles as SGML, XML, or HTML. Each section of data is prefaced by a start (<>) tag and finished with an end (</>) tag, and sections can be nested hierarchically. The Csound tags (boldface) are as follows, with explanatory comments (italics) and sample data:

<CsoundCsynthesizer>
; Csound structured data file.
<CsOptions>
; Command-line options
-W
</CsOptions>
<CsInstruments>
; Orchestra statements.
sr 44100
kr 441
ksmps 100
nchnls 2
; Instrument definitions.
; The first comment following on the same line as an instrument number is the name of the instrument.
instr 1 ;Toot1
endin
instr 2 ;Toot2
endin
</CsInstruments
<CsScore>
; Standard Csound function ("f") statements, note ("i") statements, or comments (";").
f 1 2 3 
i 1 2 3 4
</CsScore>
</CsoundSynthesizer>

Acknowledgements

Many thanks to all people that is (or has been) invloved in Csound developement:

Barry Vercoe, John Fitch, Rasmus Ekman, Michael Gogins, David Boothe, Hans Mikelson, Richard Dobson, Nicola Bernardini, Mike Berry, Matt Ingalls, Eli Breder, Richard Karpen, Michael Casey, Victor Lazzarini, Michael Clarke, Allan Lee, Perry Cook, David Macintyre, Sean Costello, Mark Dolson, Peter Neubäcker, Ville Pulkki, Dan Ellis, Marc Resibois, Tom Erbe, Paris Smaragdis, Greg Sullivan, Bill Gardner, Robin Whittle, Jens Groh

Many thanks to the authors of  the open-source libraries used in DirectCsound:

FLTK: Bill Spitzak, Michael Sweet, Craig P. Earls, and all others

Paintlib: Ulrich von Zadow, Meng Bo, Bernard Delmée, Andreas Köpf, Martin Skinner,  Gilles Vollant, Mario Westphal, Roger Willcocks, twosuns GmbH, and others

Many thank also to the developers of Libtiff, Libjpeg and Libpng