CsoundManual - Previous 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

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.


CsoundManual - Top of this section - Previous - Contents - Index - Next

Independent Preprocessing with scsort

Although the result of all score preprocessing is retained in the file score.srt after orchestra performance (it exists as soon as score preprocessing has completed), the user may sometimes want to run these phases independently. The command

          scot filename  

will process the Scot formatted filename, and leave a standard numeric score result in a file named score for perusal or later processing.

The command

          scscort < infile > outfile  

will put a numeric score infile through Carry, Tempo, and Sort preprocessing, leaving the result in outfile.

Likewise extract, also normally invoked as part of the csound command, can be invoked as a standalone program:

          extract xfile < score.sort > score.extract  

This command expects an already sorted score. An unsorted score should first be sent through scsort then piped to the extract program:

          scsort < scorefile | extract xfile > score.extract  


CsoundManual - Top of this section - Previous - Contents - Index - Next section

The EXTRACT feature

This feature will extract a segment of a sorted numeric score file according to instructions taken from a control file. The control file contains an instrument list and two time points, from and to, in the form:

          instruments 1  2  from  1:27.5  to  2:2  

The component labels may be abbreviated as i, f and t. The time points denote the beginning and end of the extract in terms of:

          [section no.] : [beat no.].   

each of the three parts is also optional. The default values for missing i, f or t are:

          all instruments, beginning of score, end of score. 

extract reads an orchestra-readable score file and produces an orchestra-readable result. Comments, tabs and extra spaces are flushed, w and a statements are added and an f0 reflecting the extract length is appended to the output. Following an extract process, the abbreviated score will contain all function table statements, together with just those note statements that occur in the from-to interval specified. Notes lying completely in the interval will be unmodified; notes that lie only partly within will have their p3 durations truncated as necessary.