THE_CSOUND_COMMAND

QUICK-REF - CsoundManual - Previous Section - Next Section - Contents - Index - Next

THE CSOUND COMMAND

csound is a command for passing an orchestra file and score file to Csound to generate a soundfile. The score file can be in one of many different formats, according to user preference. Translation, sorting, and formatting into orchestra-readable numeric text is handled by various preprocessors; all or part of the score is then sent on to the orchestra. Orchestra performance is influenced by command flags, which set the level of displays and console reports, specify 1/0 filenames and sample formats, and declare the nature of realtime sensing and control.

IMPORTANT NOTE: These are generic Csound command flags. Various platform implementations may not react the same way to different flags!

The format of a command is:

          csound [-flags] orchname scorename

where the arguments are of 2 types: flag arguments (beginning with a "-"), and name arguments (such as filenames). Certain flag arguments take a following name or numeric argument. The available flags are:

-U unam run utility program unam
-C      use Cscore processing of scorefile
-I      I-time only orch run
-n      no sound onto disk
-i fnam sound input filename
-o fnam sound output filename
-b N    sample frames (or -kprds) per software sound I/O buffer
-B N    samples per hardware sound I/O buffer
-A      create an AIFF format output soundfile
-W      create a WAV format output soundfile
-h      no header on output soundfile
-c      8-bit signed_char sound samples
-a      alaw sound samples
-8      8-bit unsigned_char sound samples
-u      ulaw sound samples
-s      short_int sound samples
-l      long_int sound samples
-f      float sound samples
-r N    orchestra srate override
-k N    orchestra krate override
-v      verbose orch translation
-m N    tty message level. Sum of: 1=note amps, 2=out-of-range msg, 4=warnings
-d      suppress all displays
-g      suppress graphics, use ascii displays
-G      suppress graphics, use Postscript displays
-S      score is in Scot format
-x fnam extract from score.srt using extract file 'fnam'
-t N    use uninterpreted beats of the score, initially at tempo N
-L dnam read Line-oriented realtime score events from device 'dnam'
-M dnam read MIDI realtime events from device 'dnam'
-F fnam read MIDIfile event stream from file 'fnam'
-P N    MIDI sustain pedal threshold (0 - 128)
-R      continually rewrite header while writing soundfile (WAV/AIFF)
-H      print a heartbeat character at each soundfile write
-N      notify (ring the bell) when score or miditrack is done
-T      terminate the performance when miditrack is done
-D      defer GEN01 soundfile loads until performance time
-z      List opcodes in this version

PC Windows-specific flags

-j num  set the number of console text rows (default 25)
-J num  set the number of console text columns (default 80)
-K num  enables MIDI IN. 'num' (optional) = MIDI IN port device id number
-q num  WAVE OUT device id number (use only if more WAVE devices are installed)
-p num  number of WAVE OUT buffers (default 4; max. 40)
-O      suppresses all console text output for better realtime performance
-e      allows any sample rate (to use only with WAVE cards supporting this feature)
-y      doesn't wait for keypress on exit
-E      allows graphic display for WCSHELL by Riccardo Bianchini
-Q num  enable MIDI OUT. 'num' (optional) = MIDI OUT port device id number
-Y      suppresses realtime WAVE OUT for better MIDI OUT timing performance
-*      yields control to the system until audio output buffer is full

DESCRIPTION:

Flags may appear anywhere in the command line, either separately or bundled together. A flag taking a Name or Number will find it in that argument, or in the immediately subsequent one. The following are thus equivalent commands:

      csound  -nm3  orchname  -Sxxfilename  scorename 
      csound  -n  -m  3  orchname  -x  xfilename  -S scorename

All flags and names are optional. The default values are:

      csound  -s  -otest  -b1024  -B1024  -m7  -P128  orchname  scorename

where orchname is a file containing Csound orchestra code, and scorename is a file of score data in standard numeric score format, optionally presorted and time-warped. If scorename is omitted, there are two default options: 1) if realtime input is expected (-L, -M or -F), a dummy scorefile is substituted consisting of the single statement 'f 0 3600' (i.e. listen for RT input for one hour); 2) else csound uses the previously processed score.srt in the current directory.

Csound reports on the various stages of score and orchestra processing as it goes, doing various syntax and error checks along the way. Once the actual performance has begun, any error messages will derive from either the instrument loader or the unit generators themselves. A csound command may include any rational combination of the following flag arguments, with default values as described:

csound -U

Invoke Utility Preprocessing programs: sndinfo, hetro, lpanal, pvanal, cvanal.

csound -I

I-time only. Allocate and initialize all instruments as per the score, but skip all P-time processing (no k-signals or a-signals, and thus no amplitudes and no sound). Provides a fast validity check of the score pfields and orchestra i-variables.

csound -n

Nosound. Do all processing, but bypass writing of sound to disk. This flag does not change the execution in any other way.

csound -i isfname

Input soundfile name. If not a full pathname, the file will be sought first in the current directory, then in that given by the environment variable SSDIR (if defined), then by SFDIR. The name stdin will cause audio to be read from standard input. If RTAUDIO is enabled, the name devaudio will request sound from the host audio input device.

csound -o osfname

Output soundfile name. If not a full pathname, the soundfile will be placed in the directory given by theenvironment variable SFDIR (if defined), else in the current directory. The name stdout will cause audio to be written to standard output. If no name is given, the default name will be test. If RTAUDIO is enabled, the name devaudio will send to the host audio output device.

csound -b Numb

Number of audio sample-frames per soundio software buffer. Large is efficient, but small will reduce audio I/O delay. The default is 1024. In realtime performance, Csound waits on audio I/O on Numb boundaries. It also processes audio (and polls for other input like MIDI) on orchestra ksmps boundaries. The two can be made synchronous. For convenience, if Numb = -N (is negative) the effective value is ksmps * N (audio synchronous with k-period boundaries). With N small (e.g. 1) polling is then frequent and also locked to fixed DAC sample boundaries.

csound -B Numb

Number of audio sample-frames held in the DAC hardware buffer. This is a threshold on which software audio I/O (above) will wait before returning. A small number reduces audio I/O delay; but the value is often hardware limited, and small values will risk data lates. The default is 1024.

csound -h

No header on output soundfile. Don't write a file header, just binary samples.

csound {-c, -a, -u, -s, -l, -f}

Audio sample format of the output soundfile. One of:

     c    8-bit signed character 
     a    8-bit a-law 
     u    8-bit u-law 
     s    short integer 
     l    long integer 
     f    single-precision float (not playable, but can be read by -i, soundin and GEN01)

csound -A

Write an AIFF output soundfile. Restricts the above formats to c, s, or l.

csound -v

Verbose translate and run. Prints details of orch translation and performance, enabling errors to be more clearly located.

csound -m Numb

Message level for standard (terminal) output. Takes the sum of 3 print control flags, turned on by the following values: 1 = note amplitude messages, 2 = samples out of range message, 4 = warning messages. The default value is m7 (all messages on).

csound -d

Suppress all displays.

csound -g

Recast graphic displays into ascii characters, suitable for any terminal.

csound -S

Interpret scorename as a Scot file and create a standard score file (named "score") from it, then sort and perform that.

csound -x xfile

Extract a portion of the sorted score score.srt, according to xfile ( see Extract).

csound -t Numb

Use the uninterpreted beats of score.srt for this performance, and set the initial tempo at Numb beats per minute. When this flag is set, the tempo of score performance is also controllable from within the orchestra ( see the tempo unit).

csound -L devname

Read Line-oriented realtime score events from device devname. The name stdin will permit score events to be typed at your terminal, or piped from another process. Each line-event is terminated by a carriage-return. Events are coded just like those in a standard numeric score , except that an event with p2=0 will be performed immediately, and an event with p2=T will be performed T seconds after arrival. Events can arrive at any time, and in any order. The score carry feature is legal here, as are held notes (p3 negative) and string arguments, but ramps and pp or np references are not.

csound -M devname

Read MIDI events from device devname.

csound -F mfname

Read MIDI events from midifile mfname.

csound -P Numb

Set MIDI sustain pedal threshold (0 - 128). The official switch value of 64 is normally too low, and is more realistic above 100. The default value of 128 will block all pedal info.

csound -N

Notify (ring the bell) when score or miditrack is done.

csound -T

Terminate the performance when miditrack is done.

PC/Windows-specific flags

csound -K num

MIDI device id number (optional, use only if MIDI devices are more than one)

csound -q num

WAVE OUT device id number (optional, use only if WAVE OUT devices are more than one)

csound -p num

number of WAVE OUT buffers (optional; default=4, maximum=40). -b (buffer length) and -p flags are related each other. Finding the optimum values for "-b" and "-p" flags 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). You now can drastically reduce buffer length and delay by using -e flag and 'rounded' sr and kr.

Note that sometimes a samller buffer length can handle sound flow better than a larger. Only experiments can lead you toward optimal '-b' values. -b and -p flags value can now 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 (till now this feature was 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.

csound -j num

console virtual text rows number.

csound -J num

console virtual text columns number.

csound -O (uppercase letter)

suppresses all printf for better realtime performance. This switch is better than '-m0' because '-m0' still leaves some message output to the console. Use both switches together for maximum performance speed.

csound -e

allows arbitrary output sample rate (for cards that support this feature).

csound -y

doesn't wait for keypress on exit.

csound -E

graphic display for WCSHELL by Riccardo Bianchini.

csound -Q num

enables MIDI OUT operations and optionally chooses device id num (if num argument is present). This 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 (see -Y flag).

csound -Y

disables WAVE OUT (for better MIDI OUT timing performances). 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.

csound -*

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. Do not use this flag when time response to gestual actions is critical.

QUICK-REF - CsoundManual - Previous Section - Next Section - Contents - Index - Next