Instrument Control

Once in a while, you may need to reinitialize an instrument while it’s running. This is done using the reinit opcode. The reinitialization can be done for all of the instrument code or only for a selected portion of the code. During the reinitialization, all of the i-time values that are set forth within the designated code lines will be recalculated. Envelope generators will start over from their starting points. The phase of oscillators will be reset.

The syntax of reinit is simple:

  reinit label

As the manual explains, during a reinitialization pass, performance is temporarily suspended (without any effect on the audio output, unless the reinitialization itself causes an effect or takes so long that the output buffer is emptied) while an initialization pass is run. This pass begins at the label specified as the argument to reinit and continues either to the end of the instrument or to an earlier point in the code designated by a rireturn statement. Performance is then resumed at the point where it left off.

reinit will often be used in conjunction with timout, but it doesn’t have to be. The syntax of the timout opcode looks like this:

  timout istrt, idur, label

This opcode creates a conditional branch during k-period cycles. Beginning at time istrt (which should usually be zero), timout causes processing to jump to the point specified by label. After idur seconds, the jump ceases, and whatever code lies between the timout statement and the label will be executed. This code may include a reinit.

Here is an example of timout that delays the start of a second oscillator:

  instr 1

  asig2 init 0

  timout 0, 0.5, contin
  asig2 oscil 0.4, 500, giSine

  kamp2 linseg 0, 0.1, 1
  asig2 = asig2 * kamp2

  contin:

  asig oscil 1, 200, giSine
  asig = asig + asig2
  kamp linen 0.7, 0, p3, 0.2
  asig = asig * kamp
  outs asig, asig

  endin

In this example, the second oscillator (whose output is asig2) and its associated amplitude envelope are ignored for the first 0.5 second, because during that time timout causes a branch to the contin label. When 0.5 second has passed, timout ceases to cause a jump, so the second oscillator will be heard.

With that preamble, the usage of reinit and timout may be easier to understand. The example given in the manual for reinit is rather artificial, but I was unable to come up with anything much more musical. In the following example, the frequency of the oscillator (set by ifreq) is changed during a reinit pass. The frequency is coming from a global k-rate variable, gkPitch, which might be doing anything.

  instr 1
  reset:
    ifreq = i(gkPitch)
    timout 0, p3/40, contin
    reinit reset
  contin:
    asig oscil 1, ifreq, giSine, -1
  rireturn
  kamp linen 0.7, 0, p3, 0.2
  asig = asig * kamp
  outs asig, asig
  endin

The point of this example is that the reinit line is executed only when timout has timed out. While timout is active, the k-period execution of the instrument code never sees reinit; it jumps past reinit to the contin label. And the value of ifreq doesn’t change, because it’s an i-time variable. Periodically, however (in this example, it happens 40 times during the note event, because the duration value for timout is p3/40), reinit causes a jump back to the reset label. Each time this happens, ifreq is given a new value based on the current value of gkPitch. The reinitialization pass then continues downward through the code, first restarting timout (so that its start time and duration will be reset in terms of the current moment) and then sending the new value of ifreq to the oscillator. The reinitialization pass then hits the rireturn opcode and terminates.

You’ll notice that the value of the optional phase parameter for oscil has been set to −1. This causes reinitialization of the waveform phase to be skipped. In the absence of a negative value for this argument, the oscillator will click whenever a reinitialization pass occurs, because its phase will be reset to the starting point.