Named Instruments
Prev | Syntax of the Orchestra | Next

## Named Instruments

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.

### Syntax

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

### Using Named Instruments

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

  | 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.

### Example

    ; ---- 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

### Author

Istvan Varga

2002

Prev | Up | Next
Macros | Home | User Defined Opcodes (UDO)