instr and endin
Every Csound project must contain at least one defined instrument. If there’s no instrument, Csound will have nothing to do. The instruments you define make up the Csound “orchestra.” The code with which you create instruments will go between the <CsInstruments> and </CsInstruments> tags in the .csd file and will follow the orchestra header. For more on what goes in the orchestra header, see Chapter 4.
Instrument definitions begin with instr, followed by a unique instrument number. Instrument definitions always end with the symbol endin, on a line by itself. endin is short for “end instrument.” These and other abbreviations in Csound date back to the early days of computing, when filenames and almost everything else had to be kept short because operating systems were simple and computer memory was expensive.
Here is a fairly generic instrument definition. It uses instr to create an instrument numbered 1. It has a few other features that will be covered later in this chapter.
instr 1 idur = p3 iamp = p4 ifreq = p5 iatk = p6
idec = p7 ipan = p8 asig oscili iamp, ifreq, giSine aout linen asig, iatk, idur, idec aoutL, aoutR pan2 aout, ipan outs aoutL, aoutR endin
An instrument can be given several different numbers. This is legal:
instr 1, 2, 3
At first glance, this might seem fairly pointless. The i-statements in the score will call this instrument, so why would you want to have a choice of numbers? Wouldn’t that just make your score more confusing? Perhaps—but when you’re writing the score, the value of the first p-field is available within the instrument code. You can get it by using the symbol p1. As a result, you could, if so inclined, define the above instrument with numbers 1, 2, and 3, and then do something like this:
ifreq = p5 if p1 == 2 then ifreq = ifreq * 2 elseif p1 == 3 then ifreq = ifreq * 3 endif
This is a trivial example, but it illustrates how defining an instrument with several numbers might be useful. Most of the code could be the same whether the instrument is referred to in the score as i1, i2, or i3. But there could be a few salient differences, and you could easily switch among them by changing one digit in an i-statement.
If the syntax in the preceding example doesn’t make sense to you, see the section on “Logic and Flow Control” later in this chapter.
A fairly new feature of Csound is the ability to give an instrument a name instead of a number. If you use a name, Csound will give the instrument a number internally, for its own purposes. In fact, you can give an instrument both one or more numbers and one or more names. The name, in double quotes, can then be used in the score in the position of p1:
i “SineTone” 0 1 0.4 220 0.1 0.1 0.3
The advantage of this approach is that the score is more human-readable. The downside is that you can’t test in the code whether p1 = “SineTone”, so mixing names and numbers is likely to be of limited utility.
As explained on the page of the manual that discusses named instruments, “An instrument name may consist of any number of letters, digits, and the underscore (_) character. However, the first character must not be a digit. Optionally, the instrument name may be prefixed with the ‘+’ character.” The point of preceding the name with ‘+’ is that when Csound is running, generating sound, it processes the instruments in numerical order. Instruments that perform audio processing on the signals coming from other instruments (that is, effects) should usually be given a higher number than the instruments whose signals they’re processing. If you fail to follow this guideline, the output of the effect will always be delayed by one k-period, because the input to a low-numbered effect will be the signal created by the source instruments during the preceding k-period. As noted above, when you give your instruments names, Csound internally assigns them numbers. When a named instrument is given a name preceded by ‘+’, Csound gives it a higher number than any of the numbered and named instruments that don’t have a ‘+’.