As a recent addition to the orchestra syntax, instruments can be defined with string names. Such named instruments are callable from the score, and are supported by a number of opcodes.
A named instrument is declared as shown below:
instr Name[, Name2[, Name3[, ...]]]
[...]
endin
A single instrument can have any number of names, and any of these names can be used to call the instrument. Additionally, it is possible to use numbers as name, denoting a standard numbered instrument, so the following declaration is also valid:
instr 100, Name1, 99, Name2, 1, 2, 3
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 (see below), for example:
instr +Reverb
For all instrument names, a number is automatically assigned (note: if the message level (-m) is not zero, these numbers are printed to the console during orchestra compilation), following these rules:
-
any unused instrument numbers are taken up in ascending order, starting from 1
-
the numbers are assigned in the order of instrument name definition, so named instruments that are defined later will always have a higher number (except if the '+' modifier is used)
-
if the instrument name was prefixed with '+', the assigned number will be higher than that of any of the (both numbered and named) other instruments without '+'. If there are multiple '+' instruments, the numbering of these will follow the order of definition, according to the above rule.
Using '+' is mainly useful for global output or effect instruments, that must be performed after the other instruments.
An example for instrument numbers:
instr 1, 2
endin
instr Instr1
endin
instr +Effect1, Instr2
endin
instr 100, Instr3, +Effect2, Instr4, 5
endin
In this example, the instrument numbers are assigned as follows:
Instr1: 3
Effect1: 101
Instr2: 4
Instr3: 6
Effect2: 102
Instr4: 7
Named instruments can be called by using the name in double quotes as the instrument number (note: the '+' character should be omitted). Currently (as of Csound 4.22.4), named instruments are supported by:
-
'i' and 'q' score events
![[Note]](images/note.png)
Notes -
in score files, unmatched quotes, and spaces or other invalid characters in the strings should be avoided, otherwise (at least with current version) unpredictable behavior may occur (this problem does not exist for -L line events). However, there is checking for undefined instruments, and in such cases, the event is simply ignored with a warning.
-
Stand-alone utilities (score sort and extract) do not support named instruments. It is still possible to sort such scores by using the -t0 option of the main Csound executable)
-
-
real-time line events (-L)
-
event, schedkwhen, subinstr, and subinstrinit opcodes
-
massign, pgmassign, prealloc, and mute opcodes
Additionaly, there is a new opcode (nstrnum) that returns the number of a named instrument:
insno nstrnum "name"
With the above example, nstrnum "Effect1" would return 101. If an instrument with the specified name does not exist, an init error occurs, and -1 is returned.
; ---- orchestra ---- sr = 44100 ksmps = 10 nchnls = 1 prealloc "SineWave", 20 prealloc "MIDISineWave", 20 massign 1, "MIDISineWave" gaOutSend init 0 instr +OutputInstr out gaOutSend clear gaOutSend endin instr SineWave a1 oscils p4, p5, 0 vincr gaOutSend, a1 endin instr MIDISineWave iamp veloc inote notnum icps = cpsoct(inote / 12 + 3) a1 oscils iamp * 100, icps, 0 vincr gaOutSend, a1 endin ; ---- score ---- i "SineWave" 0 2 12000 440 i "OutputInstr" 0 3 e