Description

Cette instruction est nécessaire pour activer un instrument à une date précise et pour une certaine durée. Les valeurs des champs de paramètre sont passées à cet instrument avant son initialisation, et demeurent valides durant toute son exécution.

Syntaxe

i  p1  p2  p3  p4  ...

Initialisation

p1 -- Numéro d'instrument, habituellement un nombre entier non négatif. Une partie décimale facultative permet d'ajouter une étiquette indiquant des liaisons entre des notes particulières d'aggrégats consécutifs. Un p1 négatif (incluant une étiquette) peut être utilisé pour faire cesser une note « tenue » particulière. Dans le cas d'un instrument nommé, on peut obtenir le même effet en ayant un '-' comme premier caractère du nom.

p2 -- Date de début en unités arbitraires appelées pulsations.

p3 -- Durée en pulsations (habituellement positive). Une valeur négative démarre une note tenue (voir aussi ihold). On peut aussi utiliser une valeur négative pour les instruments 'toujours actifs' comme la réverbération. Ces notes ne sont pas terminées par des instruction s. Une valeur nulle provoquera une passe d'initialisation sans exécution (voir aussi instr).

p4 ... -- Paramètres dont la signification est déterminée par l'instrument.

Exécution

Une pulsation vaut une seconde, à moins qu'il n'y ait une instruction t dans cette section de la partition ou une option -t dans la ligne de commande.

Les dates de début ou d'action sont relatives au début d'une section (voir l'instruction s), qui reçoit la date 0.

Dans une section, les instructions de note peuvent être placées dans n'importe quel ordre. Avant d'être envoyées à l'orchestre, les instructions non triées de la partition doivent être traitées par la fonction Sort, qui les ordonnera par valeurs de p2 croissantes. Les notes ayant la même valeur en p2 seront triées par p1 croissants ; si elles ont le même p1, alors par p3 croissants.

Les notes peuvent être superposées, c'est-à-dire qu'un seul instrument peut jouer n'importe quel nombre de notes simultanément. (Les copies nécessaires de l'espace de données de l'instrument seront allouées dynamiquement par le chargeur de l'orchestre). Chaque note se termine normalement à la fin de sa durée en p3, ou à la réception d'un signal MIDI noteoff. Un instrument peut modifier sa propre durée en changeant la valeur de son p3 pendant l'initialisation de la note, ou en se prolongeant lui-même par l'action d'une unité linenr ou xtratim.

Un instrument peut être activé et réglé pour une durée indéfinie soit en lui donnant un p3 négatif soit en incluant un ihold dans le code de son temps-i. Si une note tenue est active, une instruction i avec un p1 correspondant ne provoquera pas une nouvelle allocation mais prendra l'espace de données de la note tenue. Les nouveaux p-champs (y compris p3) seront maintenant effectifs, et une passe de temps-i sera exécutée pendant laquelle les unités peuvent être soit initialisées à nouveau soit autorisées à continuer comme requis pour une note liée (voir tigoto). Une note tenue peut être suivie soit par une autre note tenue soit par une note de durée finie. Une note tenue continuera à être jouée au-delà des fins de section (voir l'instruction s). Elle est arrêtée seulement par un turnoff ou par une instruction i avec un p1 négatif correspondant ou par une instruction e.

Il est possible d'avoir plusieurs instances (habituellement, mais pas forcément, des notes de hauteurs différentes) du même instrument, tenues simultanément, via des valeurs négatives de p3. L'instrument peut ensuite recevoir de nouveaux paramètres de la partition. C'est utile pour éviter de longs linseg codés en dur, et peut être accompli en ajoutant une partie décimale au numéro de l'instrument.

Par exemple, pour tenir trois copies de l'instrument 10 dans un accord :

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

Les instructions i suivantes peuvent faire référence aux mêmes instances de note active, et si la définition de l'instrument est faite proprement, les nouveaux p-champs peuvent servir à changer le caractère des notes jouées. Par exemple, pour faire glisser l'accord précédent d'une octave vers le haut et le laisser résonner :

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

	Astuce
	Pour la terminaison des notes, il faut tenir compte du fait que i 1.1 == i 1.10 et que i 1.1 != i 1.01. Le nombre maximum de positions décimales que l'on peut utiliser dépend de la précision avec laquelle Csound a été compilé (Csound Double (64 bit) ou Float (32 bit))

La définition de l'instrument doit prendre ceci en compte, cependant, spécialement si l'on veut éviter les clics (voir l'exemple ci-dessous).

Noter que la notation décimale du numéro d'intrument ne peut pas être utilisée en conjonction avec le MIDI en temps réel. Dans ce cas, l'instrument serait monodique tant qu'une note est tenue.

Les notes liées à des instances précédentes du même instrument, devraient éviter la plus grande partie de l'initialisation au moyen de tigoto, sauf pour les valeurs entrées dans la partition. Par exemple, tous les opcodes de lecture de table dans l'instrument, seront habituellement sautés en initialisation, car ils mémorisent en interne leur phase. Si celle-ci est brutalement modifiée, on entendra des clics en sortie.

Noter que plusieurs opcodes (comme delay et reverb) sont prévus pour une initialisation facultative. Pour utiliser cette possibilité, l'opcode tival est approprié. Ainsi, il n'y a pas besoin de les escamoter par un saut tigoto.

A partir de la version 3.53 de Csound, les chaînes sont reconnues dans les p-champs des opcodes qui les acceptent (convolve, adsyn, diskin, etc.). Il ne peut y avoir qu'une seule chaîne par ligne de la partition.

On peut aussi terminer une note depuis la partition en utilisant un nombre négatif pour l'instrument (p1). Cela équivaut à utiliser l'opcode turnoff2. Lorsqu'une note est terminée depuis la partition, elle peut avoir un relâchement (si xtratim ou des opcodes avec une section de relâchement tels que linenr sont utilisés) et seules les notes ayant la même partie fractionnaire sont arrêtées. De plus, seule la dernière instance de l'instrument est arrêtée, si bien qu'il faut autant de numéros d'instrument négatifs que de numéros positifs pour que toutes les notes soient arrêtées.

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

; noter que les p-champs suivant p2 sont ignorés
; si le numéro d'instrument est négatif
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

Exemples

Voici un exemple de l'instruction i. Il utilise le fichier 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>

Crédits

Texte supplémentaire (Version 4.07 de Csound) expliquant les notes liées, publié par Rasmus Ekman d'après une note de David Kirsh, postée sur la liste de courrier électronique de Csound. Instrument en exemple par Rasmus Ekman.

Mise à jour Août 2002 grâce à une note de Rasmus Ekman. Il n'y a plus de limite codée en dur à 200 instruments.