The Alternative Csound Reference Manual
Previous |  | 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 files subinstr.orc and subinstr.sco.

Example 1. Example of the subinstr opcode.

    /* subinstr.orc */
    ; 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
    /* subinstr.orc */

    /* subinstr.sco */
    ; Table #1, a sine wave.
    f 1 0 16384 10 1

    ; Play Instrument #2 for one second.
    i 2 0 1
    e
    /* subinstr.sco */

Here is an example of the subinstr opcode using a named instrument. It uses the files subinstr_named.orc and subinstr_named.sco.

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

    /* subinstr_named.orc */
    ; 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
    /* subinstr_named.orc */

    /* subinstr_named.sco */
    ; Table #1, a sine wave.
    f 1 0 16384 10 1

    ; Play Instrument #1 for one second.
    i 1 0 1
    e
    /* subinstr_named.sco */

## Credits

New in version 4.21

Previous | Home | Next
strset | Up | subinstrinit