Csound can be operated in a variety of modes and configurations. The original method for running Csound was as a console program (DOS prompt for Windows, Terminal for Mac OS X). This, of course, still works. Running csound without any arguments prints out a list of command-line options, which are more fully explained in the Command Line Flags (by Category) section. Normally, the user executes something like:
csound myfile.csd
or separate orchestra (orc) and score (sco) files can be used:
csound myorchestra.orc myscore.sco
You can find many .csd files in the examples folder. Most opcode entries in this manual also include simple .csd files showing the usage of the opcode.
Csound also has several ways of producing output. It can:
- Read and write soundfiles (off-line rendering) - Using the -o and -i flags specifying an output filename.
- Read and write digital audio using a sound card (real-time rendering) - Using the -odac and -iadc flags
- Read and write MIDI files (non-realtime) - Using the -F and --midioutfile flags.
- Read and write MIDI using a MIDI interface and controller (real-time control) - Using the -M and -Q flags.
![[The Csound5 Modular structure.]](images/engine.png)
The Csound5 Modular structure.
Csound's processing buffers
Csound processes audio in sample blocks called buffers. There are three separate buffer layers:
spout = Csound's innermost software buffer, contains ksmps sample frames. Csound processes real-time control events once every ksmps sample frames.
-b = Csound's intermediate software buffer (the "software" buffer), in sample frames. Should be (but does not need to be) an integral multiple of ksmps (can equal ksmps too). Once per ksmps sample frames, Csound copies spout to the -b buffer. Once per -b sample frames, Csound copies the -b buffer to the -B "hardware" buffer.
-B = The sound card's internal buffer (the "hardware" buffer), in sample frames. Should be (and may need to be) an integral multiple of -b. If Csound misses delivering a -b one time, the extra -b sample frames in -b are still there for the sound card to keep playing while Csound catches up. But they can be the same size if you're willing to bet Csound can always keep up with the sound card.
Amplitude values in Csound are always relative to a "0dbfs" value representing the peak available amplitude before clipping, in either an AD/DA codec, or in a soundfile with a defined range (which both WAVE and AIFF are). In the original Csound, this value was always 32767, corresponding to the range of a 16bit soundfile or 16bit AD/DA codec, Csound's only possible output back then. This remains the default peak amplitude for Csound, for backward compatibility and you will find most of this manual's examples still use this value (hence you find large amplitude values like 10000).
The 0dbfs value enables Csound to produce appropriately scaled values to whatever output format is being used, whether 24bit integer, 32bit floats, or even 32bit integers. Put another way, the literal amplitude values you write in a Csound instrument only match those written literally to the file if the 0dbfs value in Csound corresponds exactly to that of the output sample format. The consequence of this approach is that you can write a piece with a certain amplitude and have it render correctly and identically (setting aside of course the better dynamic range of the high-res formats) whether written to an integer or floats file, or rendered in real-time.
![[Note]](images/note.png) | Note |
|---|---|
The one exception to this is if you choose to write to a "raw" (headerless) file format. In such cases the internal 0dbfs value is meaningless, and whatever values you use are written unmodified. This does enable arbitrary data to be generated or processed by Csound. It is a relatively exotic thing to do, but some users need it. |
You can choose to redefine the 0dbfs value in the orchestra header, purely for your own convenience or preference. Many people will choose 1.0 (the standard for SAOL, other software like Pure Data, and for many plugin standards such as VST, LADSPA, CoreAudio AudioUnits, etc), but any value is possible.
The common factor in defining amplitudes is the decibel (dB) scale, with 0dBFS always understood as digital peak; hence "0dbfs" means "0dB Full-Scale value". This measure is different to actual amplitude values, since amplitude values are a linear scale which show the actual oscillation around 0, so they can be positive or negative. Decibel values are an absolute logarithmic scale, but can be useful for most opcodes as well. You can convert amplitude to and from decibels using the ampdb,ampdbfs, dbamp and dbfsamp functions. This way, Csound enables the programmer to express all amplitudes in dB - lower amplitudes will then be represented by negative dB values. This reflects industry practice (e.g. in level meters in mixers, etc).
For example the same dB level of -6dB (half as loud) is expressed as an explicit amplitude according to 0dbfs as:
Table 1. dBFS in relation to amplitude
| dBFS | 0dbfs = 32767 (default) | 0dbfs = 1 | 0dbfs = 1000 |
|---|---|---|---|
| 0 | 32767 | 1 | 1000 |
| -6 | 16384 | 0.5 | 500 |
Some Csound users might therefore be minded to express all levels in dBFS, and obviate any confusion or ambiguity of level that may otherwise arise when using explicit amplitude values. The decibel scale reflects the response of the ear pretty closely, and that when you want to express a really quiet level, it might be easier and more expressive to write "-46dB" than "0.005" or "163.8".