<- C I ->

The Unix 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.

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
soundfile Utility pre-processing
-I, -n
sound output inhibitors
-iName, -oName
sound I/O filenames
-bNumb, -BNumb, -h
audio buffers & header control
-A, -c, -a, -u, -s, -1, -f
audio output formats
-v, -mNumb, -d, -g
message & display levels
-S, -xName, -tNumb
score formats & tempo control
-LName
line-oriented realtime event stream
-MName, -FName, -PNumb
MIDI event streams
notify or terminate when done

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.

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 the environment 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.

csound -U
Invoke the Csound Utility programmes .

<- C I ->
Prepared from the MIT Media Lab Csound Manual, PJN, Nov 1994.