nstance
Prev | Orchestra Opcodes and Operators | Next

## nstance

nstance — Schedules a new instrument instance, storing the instance handle in a variable.

## Description

Schedules a new instrument nstance, returning a handle that can be used later to refer directly to the running nstance. This opcode is similar to schedule, but has the added facility of retrieving the nstance handle.

## Syntax

    iHandle nstance insnum, iwhen, idur [, ip4] [, ip5] [...]

    iHandle nstance "insname", iwhen, idur [, ip4] [, ip5] [...]

## Initialization

iHandle -- this variable will contain a handle to the event instance. It can be used, for example, to stop the given instrument instance via the turnoff opcode. Note that the instance handle is only valid once the instrument is initialised.

insnum -- instrument number. Equivalent to p1 in a score i statement. insnum must be a number greater than the number of the calling instrument.

“insname” -- A string (in double-quotes) representing a named instrument.

iwhen -- start time of the new event. Equivalent to p2 in a score i statement. iwhen must be nonnegative. If iwhen is zero, insum must be greater than or equal to the p1 of the current instrument.

idur -- duration of event. Equivalent to p3 in a score i statement.

ip4, ip5, ... -- Equivalent to p4, p5, etc., in a score i statement.

## Performance

nstance adds a new score event. The arguments, including options, are the same as in a score. The iwhen time (p2) is measured from the time of this event.

If the duration is zero or negative the new event is of MIDI type, and inherits the release sub-event from the scheduling instruction.

| Note
Note that the nstance opcode cannot accept string p-fields. If you need to pass strings when instantiating an instrument, use the scoreline or scoreline_i opcode.

## Examples

Here is an example of the nstance opcode. It uses the file nstance.csd.

Example 669. Example of the nstance opcode.

See the sections Real-time Audio and Command Line Flags for more information on using command line flags.

    <CsoundSynthesizer>
    <CsOptions>
    ; Select audio/midi flags here according to platform
    ; Audio out   Audio in
    -odac         ;;;RT audio out
    ; For Non-realtime ouput leave only the line below:
    ; -o nstance.wav -W ;;; for file output any platform
    </CsOptions>
    <CsInstruments>

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

    instr 1 ; Instrument #1 - oscillator with a high note.

      iHandle nstance 2, .3, p3     ; Play Instrument #2 0.3 seconds later
      a1 oscils .5, 880, 1          ; a high note
      outs a1 * .5, a1              ; ... a bit to the right
      print iHandle
    endin

    instr 2 ; Instrument #2 - oscillator with a low note.

      a1 oscils .5, 110, 1          ; a low note
      outs a1, a1 * .5              ; ... a bit to the left
    endin

    </CsInstruments>
    <CsScore>
    f 1 0 16384 10 1    ; a sine wave.

    i 1 0 1
    i 1 2 .5
    e
    </CsScore>
    </CsoundSynthesizer>

## See also

Instrument Invocation

More information on this opcode: http://www.csoundjournal.com/issue15/phrase_loops.html , written by Jim Aikin

## Credits

Author: Victor Lazzarini
November 2013

Prev | Up | Next
nsamp | Home | ntom