Description

This statement calls for an instrument to be made active at a specific time and for a certain duration. The parameter field values are passed to that instrument prior to its initialization, and remain valid throughout its Performance.

Syntax

i  p1  p2  p3  p4  ...

Initialization

p1 -- Instrument number, usually a non-negative integer. An optional fractional part can provide an additional tag for specifying ties between particular notes of consecutive clusters. A negative p1 (including tag) can be used to turn off a particular “held” note. In the case of a named instrument it can be negated by having a `-' as the first character of the string.

p2 -- Starting time in arbitrary units called beats.

p3 -- Duration time in beats (usually positive). A negative value will initiate a held note (see also ihold). A negative value can also be used for 'always on' instruments like reverberation. These notes are not terminated by s statements A zero value will invoke an initialization pass without performance (see also instr).

p4 ... -- Parameters whose significance is determined by the instrument.

Performance

Beats are evaluated as seconds, unless there is a t statement in this score section or a -t flag in the command-line.

Starting or action times are relative to the beginning of a section ( see s statement), which is assigned time 0.

Note statements within a section may be placed in any order. Before being sent to an orchestra, unordered score statements must first be processed by Sorter, which will reorder them by ascending p2 value. Notes with the same p2 value will be ordered by ascending p1; if the same p1, then by ascending p3.

Notes may be stacked, i.e., a single instrument can perform any number of notes simultaneously. (The necessary copies of the instrument's data space will be allocated dynamically by the orchestra loader.) Each note will normally turn off when its p3 duration has expired, or on receipt of a MIDI noteoff signal. An instrument can modify its own duration either by changing its p3 value during note initialization, or by prolonging itself through the action of a linenr or xtratim unit.

An instrument may be turned on and left to perform indefinitely either by giving it a negative p3 or by including an ihold in its i-time code. If a held note is active, an i statement with matching p1 will not cause a new allocation but will take over the data space of the held note. The new pfields (including p3) will now be in effect, and an i-time pass will be executed in which the units can either be newly initialized or allowed to continue as required for a tied note (see tigoto). A held note may be succeeded either by another held note or by a note of finite duration. A held note will continue to perform across section endings (see s statement). It is halted only by turnoff or by an i statement with negative matching p1 or by an e statement

It is possible to have multiple instances (usually, but not necessarily, notes of different pitches) of the same instrument, held simultaneously, via negative p3 values. The instrument can then be fed new parameters from the score. This is useful for avoiding long hard-coded linsegs, and can be accomplished by adding a decimal part to the instrument number.

For example, to hold three copies of instrument 10 in a simple chord:

i10.1    0    -1    7.00
i10.2    0    -1    7.04
i10.3    0    -1    7.07

Subsequent i statements can refer to the same sounding note instances, and if the instrument definition is done properly, the new p-fields can be used to alter the character of the notes in progress. For example, to bend the previous chord up an octave and release it:

i10.1    1    1    8.00
i10.2    1    1    8.04
i10.3    1    1    8.07

	Tip
	When turning off notes, bear in mind that i 1.1 == i 1.10 and i 1.1 != i 1.01. The maximum number of decimal places that can be used depends on the precision Csound was compiled with.

The instrument definition has to take this into account, however, especially if clicks are to be avoided (see the example below).

Note that the decimal instrument number notation cannot be used in conjunction with real-time MIDI. In this case, the instrument would be monophonic while a note was held.

Notes being tied to previous instances of the same instrument, should skip most initialization by means of tigoto, except for the values entered in score. For example, all table reading opcodes in the instrument, should usually be skipped, as they store their phase internally. If this is suddenly changed, there will be audible clicks in the output.

Note that many opcodes (such as delay and reverb) are prepared for optional initialization. To use this feature, the tival opcode is suitable. Therefore, they need not be hidden by a tigoto jump.

Beginning with Csound version 3.53, strings are recognized in p-fields for opcodes that accept them (convolve, adsyn, diskin, etc.). There may be only one string per score line.

You can also turnoff notes from the score by using a negative number for the instrument (p1). This is equivalent to using the turnoff2 opcode. When a note is turned off from the score, it is allowed to release (if xtratim or opcodes with release section like linenr are used) and only notes with the same fractional part are turned off. Also, only the last instance of the instrument will be turned off, so there have to be as many negative instrument numbers as positive ones for all notes to be turned off.

i 1.1    1    300    8.00
i 1.2    1    300    8.04
i 1.3    1    -300    8.07
i 1.3    1    -300    8.09

; notice that p-fields after p2 will be ignored if 
; instrument number is negative
i -1.1    3    1    4.00
i -1.2    4    51    4.04
i -1.3    5    1    4.07
i -1.3    6    10    4.09
	

Examples

Here is an example of the i statement. Play i_statement.csd

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
-odac     ;;;realtime audio out
;-iadc    ;;;uncomment -iadc if RT audio input is needed too
; For Non-realtime ouput leave only the line below:
; -o i_statement.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>

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

instr 10
        
  icps     init      cpspch(p4)                  ; Get target pitch from score event
  iportime init      abs(p3)/7                   ; Portamento time dep on note length
  iamp0    init      p5                          ; Set default amps
  iamp1    init      p5
  iamp2    init      p5
      
  itie     tival                                 ; Check if this note is tied,
  if itie  ==  1     igoto nofadein              ; if not fade in
  iamp0    init      0

nofadein:
  if p3    < 0       igoto nofadeout             ; Check if this note is held, if not fade out
  iamp2    init      0    

nofadeout:
  ; Now do amp from the set values:
  kamp     linseg    iamp0, .03, iamp1, abs(p3)-.03, iamp2
        
  ; Skip rest of initialization on tied note:
           tigoto    tieskip

  kcps     init      icps                        ; Init pitch for untied note
  kcps     port      icps, iportime, icps        ; Drift towards target pitch

  kpw      oscil     .4, rnd(1), 1, rnd(.7)      ; A simple triangle-saw oscil
  ar       vco       kamp, kcps, 3, kpw+.5, 1, 1/icps
        
  ; (Used in testing - one may set ipch to cpspch(p4+2)
  ;       and view output spectrum)
  ;       ar oscil kamp, kcps, 1

          outs        ar, ar

tieskip:                                        ; Skip some initialization on tied note

endin
</CsInstruments>
<CsScore>
f1   0 8192 10 1            ; Sine

i10.1    0    -1    7.00    .15
i10.2    0    -1    7.04
i10.3    0    -1    7.07
i10.1    1    -1    8.00  
i10.2    1    -1    8.04
i10.3    1    -1    8.07
i10.1    2     1    7.11  
i10.2    2     1    8.04  
i10.3    2     1    8.07
  e
</CsScore>
</CsoundSynthesizer>

Credits

Additional text (Csound Version 4.07) explaining tied notes, edited by Rasmus Ekman from a note by David Kirsh, posted to the Csound mailing list. Example instrument by Rasmus Ekman.

Updated August 2002 thanks to a note from Rasmus Ekman. There is no longer a hard limit of 200 instruments.