subinstr
Prev | Orchestra Opcodes and Operators | Next

## subinstr

subinstr — Creates and runs a numbered instrument instance.

## Description

Creates an instance of another instrument and is used as if it were an opcode.

## Syntax

    a1, [...] [, a8] subinstr instrnum [, p4] [, p5] [...]

    a1, [...] [, a8] subinstr "insname" [, p4] [, p5] [...]

## Initialization

instrnum -- Number of the instrument to be called.

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

For more information about specifying input and output interfaces, see Calling an Instrument within an Instrument.

## Performance

a1, ..., a8 -- The audio output from the called instrument. This is generated using the signal output opcodes.

p4, p5, ... -- Additional input values the are mapped to the called instrument p-fields, starting with p4.

The called instrument's p2 and p3 values will be identical to the host instrument's values. While the host instrument can control its own duration, any such attempts inside the called instrument will most likely have no effect.

## See Also

Calling an Instrument within an Instrument, event, schedule, subinstrinit

## Examples

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

Example 441. Example of the subinstr 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           -iadc    ;;;RT audio I/O
    ; For Non-realtime ouput leave only the line below:
    ; -o subinstr.wav -W ;;; for file output any platform
    </CsOptions>
    <CsInstruments>

    ; Initialize the global variables.
    sr = 44100
    kr = 4410
    ksmps = 10
    nchnls = 1

    ; Instrument #1 - Creates a basic tone.
    instr 1
      ; Print the value of p4, should be equal to
      ; Instrument #2's iamp field.
      print p4

      ; Print the value of p5, should be equal to
      ; Instrument #2's ipitch field.
      print p5

      ; Create a tone.
      asig oscils p4, p5, 0

      out asig
    endin

    ; Instrument #2 - Demonstrates the subinstr opcode.
    instr 2
      iamp = 20000
      ipitch = 440

      ; Use Instrument #1 to create a basic sine-wave tone.
      ; Its p4 parameter will be set using the iamp variable.
      ; Its p5 parameter will be set using the ipitch variable.
      abasic subinstr 1, iamp, ipitch

      ; Output the basic tone that we have created.
      out abasic
    endin

    </CsInstruments>
    <CsScore>

    ; Table #1, a sine wave.
    f 1 0 16384 10 1

    ; Play Instrument #2 for one second.
    i 2 0 1
    e

    </CsScore>
    </CsoundSynthesizer>

Here is an example of the subinstr opcode using a named instrument. It uses the file subinstr_named.csd.

Example 442. Example of the subinstr opcode using a named instrument.

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

    ; Initialize the global variables.
    sr = 44100
    kr = 4410
    ksmps = 10
    nchnls = 1

    ; Instrument "basic_tone" - Creates a basic tone.
    instr basic_tone
      ; Print the value of p4, should be equal to
      ; Instrument #2's iamp field.
      print p4

      ; Print the value of p5, should be equal to
      ; Instrument #2's ipitch field.
      print p5

      ; Create a tone.
      asig oscils p4, p5, 0

      out asig
    endin

    ; Instrument #1 - Demonstrates the subinstr opcode.
    instr 1
      iamp = 20000
      ipitch = 440

      ; Use the "basic_tone" named instrument to create a
      ; basic sine-wave tone.
      ; Its p4 parameter will be set using the iamp variable.
      ; Its p5 parameter will be set using the ipitch variable.
      abasic subinstr "basic_tone", iamp, ipitch

      ; Output the basic tone that we have created.
      out abasic
    endin

    </CsInstruments>
    <CsScore>

    ; Table #1, a sine wave.
    f 1 0 16384 10 1

    ; Play Instrument #1 for one second.
    i 1 0 1
    e

    </CsScore>
    </CsoundSynthesizer>

## Credits

New in version 4.21

Prev | Up | Next
strupperk | Home | subinstrinit