The Orchestra Header

At the top of the <CsInstruments> area of the .csd file (or at the beginning of an .orc file, if you’re using Csound the old-fashioned way), you need to include a header. The code in the orchestra header gives Csound some vital information, without which it can’t run. The header will look something like this:

  sr = 44100
  ksmps = 10
  nchnls = 2
  0dbfs = 1

The first line sets the sample rate (sr) of the output file or the real-time data stream being sent to your audio interface. A value of 44100 is standard, because it’s the sampling rate used by audio CDs, but depending on your needs and the capabilities of your hardware, you may want to use a higher number or possibly (though it’s unlikely) a lower one. Csound can produce audio with any sample rate, but your audio hardware will probably only be able to use a few standard rates, such as 44100, 48000, 88200, and 96000.

The next line sets the number of samples in each k-cycle. The precise meaning of this setting will be explained in Chapter 6, “Building Your Own Instruments and Effects,” in the section “i- versus k- versus a-.” For now, all you need be concerned about are two things. First, ksmps should usually be an integer factor of the value you’ve set for the hardware buffer (which is determined by the -B command-line flag). Generally the value of -B will be a power of 2, such as 512, so values for ksmps of 1, 2, 4, 8, 16, and so on should work. Second, a higher value of ksmps will save on CPU power but will also reduce the audio quality—perhaps imperceptibly, but perhaps very perceptibly, depending on how your instruments are designed. Some Csound users set ksmps to 128 while developing their music, because more complex orchestras can play in real time when this value is higher, but they change it to 1 when rendering the finished piece to the hard drive, as that doesn’t need to be a real-time process.

Tip If you’re using Csound live, a higher setting for ksmps will put less load on your CPU, so you’ll be less likely to hear the sound break up.

The nchnls setting tells Csound how many output channels you want. Normally this will be set to 2 (for stereo sound) or 1 (for monaural). But if you have a multi-channel audio interface or want to use Csound for quadrophonic or surround sound applications, you’ll need a higher setting for nchnls. The details of how to set up your system for multi-channel operation are beyond the scope of this book.

The 0dbfs setting tells Csound what numerical value will be the maximum for the audio signals your .csd will create. In the early days, Csound’s maximum output level was set at 32,768, because the output was 16-bit audio. The largest number that can be expressed with 16 binary digits (bits) is 65,536—and if you want to include both positive and negative numbers, as you’ll need to do in order to describe audio waveforms, half of the values will be below zero, so you’ll be left with a maximum value of plus or minus 32,768.

Modern digital audio systems, however, are capable of much better sound quality than this. If you look at the General tab in CsoundQt’s Configuration box, you’ll see that Csound can create files in 16-bit, 24-bit, or 32-bit floating-point format. The numbers used in these formats can get far larger than 32,768, so using them in your orchestra code would be impractical. The 0dbfs setting bypasses that issue. After setting 0dbfs to 1.0, you can deal with all of your audio levels as decimal point values between 0.0 and 1.0. This is very convenient and is the preferred method, but older .csd files used as examples in some texts have no setting for 0dbfs. If this value is not set in the orchestra header, Csound defaults to the original value, 0dbfs=32768.

If your code produces audio values higher than the setting for 0dbfs, the output will clip. If only a few samples exceed this level, you may not hear the clipping, but if you listen closely, the crackling distortion may be audible. When larger numbers of samples clip, the results will be nasty.

One quick way to get rid of clipping distortion on the output is to increase the value of 0dbfs. When you increase the value, the output level of your sound will fall, so the distortion will go away. However, writing good code will become harder, because each time you add or edit an instrument, you’ll need to remember what value you’ve set for 0dbfs. It’s a better procedure to get rid of clipping by editing the instrument code.

Other Items in the Header

The code in the instrument header is run when Csound starts. Because of this, you’ll often use it to set up global variables and data structures of various kinds. The code for user-defined opcodes (UDOs) is included in the header area; we’ll have more to say about UDOs in Chapter 7, “Thirty Opcodes You Must Know.” Macros can be defined in the header; these are discussed later in this chapter.

In The Canonical Csound Reference Manual you’ll find a page listing a number of global reserved symbols that can be used in the header. In addition to the items we’ve already looked at, the list includes ctrlinit, ftgen, kr, massign, pgmassign, pset, seed, and strset. We’ll look at ctrlinit, massign, pgmassign, and pset in Chapter 10, “Using Csound with MIDI, OSC, Pd, Python, and Live Audio,” when we explore using Csound with MIDI. kr used to be required, but it’s now optional and redundant; if you use it, it should always be set so that kr * ksmps = sr.

ftgen is used for creating data tables and is more or less equivalent to f-statements included in the score. We’ll have more to say about it in Chapter 7.

seed is used for seeding Csound’s random number generators, including the noise sources. Setting seed = 0 will seed the random number generators from the computer’s system clock, in which case different random numbers will be generated each time the music is played. Any other value for seed will cause the random number generators to operate predictably—that is, they’ll generate the same series of quasi-random output values each time the piece is played. This can be useful both for testing purposes and in computer-assisted composition: You can keep changing the value of seed until you hear a pattern of notes that you like.

The header is also the place where you’ll create global variables. These begin with the letter g; Csound’s system for naming variables is explained in Chapter 6, “Building Your Own Instruments and Effects.” In the tutorial in Chapter 3, we’ve already used global audio-rate variables and global initialization-pass variables. Control-rate variables can also be put in the header. Here’s a quick example:

  giBaseFrequency = 33
  gkControlBus init 0
  gaAudioBus init 0

Note the use of the init opcode here. giBaseFrequency is an i-time variable, so its value can be set using the equals sign. But the data in gkControlBus and gaAudioBus will almost certainly change while the music is playing, so an equals sign wouldn’t make sense. (In fact, it will generate a compiler error, so your file won’t run.) The init opcode tells Csound the initial (starting) value of the signal, which should usually be zero.

If you’re using Csound’s zak patching system to send signals from one instrument to another, you’ll need to put the zakinit opcode in the header. You can read about zakinit and the other zak opcodes in The Canonical Csound Reference Manual.

Last but not least, any user-defined opcodes should be placed in the orchestra header, after everything else and before the beginning of your instrument code.