The Command Line

Csound was originally designed to be run from the command line. The command line was a normal user interface element in computers in the 1970s and early 1980s, before the graphical user interface came to dominate the world of computing. The command line is still available in modern computers: In the Mac OS, you can use the command line (for Csound or for many other purposes) by going to Applications:Utilities and opening the Terminal program. In Windows, the Command Prompt is found in the All Programs/Accessories folder in the Start Menu. The command line is used more often in Linux systems, though Linux distributions also have graphical user interfaces.

This heritage is important for several reasons. For one thing, you can still run Csound from a command line if you want or need to. Here is an example of a command line invoking Csound, as given in The Canonical Csound Reference Manual:

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

Some of the symbols (such as -n, -m, and -S) are called command-line flags. They tell Csound how you would like it to operate. A complete list of command-line flags is included in the manual, and you can also display it by opening a Command Prompt (Windows) or Terminal (Mac OS) and typing csound. If Csound is properly installed, most of the available command-line flags will be displayed in response to this command. In addition to zero or more command-line flags, the Csound command expects to see three filenames—one for an orchestra, one for a score, and one for the output audio file that is to be written to the computer’s hard drive. However, in place of an output filename you can use the -odac flag with a number that tells Csound what real-time output port you would like the audio sent to.

In early versions of Csound, the orchestra (the code defining one or more instruments) would be stored in a file with the filename extension .orc, while the score (the code listing the events that were to be played using the instruments) would be in a file with the filename extension .sco. These filenames would be supplied separately on the command line (as orchname and score-name in the line above). Today, a single .csd file usually contains both the orchestra and the score, so this one filename can be given on the command line.

The complete list of command-line flags can be a bit intimidating. Among the more useful items are:

-odac sets the real-time audio output.
-M sets the MIDI input device.
--displays causes the contents of f-tables to be displayed as they’re being created. (If you’re using CsoundQt, you’ll need to create a Graph widget to display the data.) Note that --displays is the default, but the code in the .csoundrc file installed in Windows systems overrides it.
-B sets the number of audio samples in the real-time output hardware buffer.
-b sets the number of audio samples in the real-time output software buffer.

All of these flags except --displays must be followed by numerical arguments. If you’re using CsoundQt, you’ll normally set the values in the Configuration box rather than in the <CsOptions> area.