chn

chn — Declare a channel of the named software bus.

Description

Declare a channel of the named software bus, with setting optional parameters in the case of a control channel. If the channel does not exist yet, it is created, with an inital value of zero or empty string. Otherwise, the type (control, audio, or string) of the existing channel must match the declaration, or an init error occurs. The input/output mode of an existing channel is updated so that it becomes the bitwise OR of the previous and the newly specified value.

Syntax

 chn_k Sname, imode[, itype, idflt, imin, imax]
 chn_a Sname, imode
 chn_S Sname, imode

Initialization

imode -- sum of at least one of 1 for input and 2 for output.

itype (optional, defaults to 0) -- channel subtype for control channels only. Possible values are:

  • 0: default/unspecified (idflt, imin, and imax are ignored)

  • 1: integer values only

  • 2: linear scale

  • 3: exponential scale

idflt (optional, defaults to 0) -- default value, for control channels with non-zero itype only. Must be greater than or equal to imin, and less than or equal to imax.

imin (optional, defaults to 0) -- minimum value, for control channels with non-zero itype only. Must be non-zero for exponential scale (itype = 3).

imax (optional, defaults to 0) -- maximum value, for control channels with non-zero itype only. Must be greater than imin. In the case of exponential scale, it should also match the sign of imin.

Notes

The channel parameters (imode, itype, idflt, imin, and imax) are only hints for the host application or external software accessing the bus through the API, and do not actually restrict reading from or writing to the channel in any way. Also, the initial value of a newly created control channel is zero, regardless of the setting of idflt.

For communication with external software, using chnexport may be preferred, as it allows direct access to orchestra variables exported as channels of the bus, eliminating the need for using chnset and chnget to send or receive data.

Performance

chn_k, chn_a, and chn_S declare a control, audio, or string channel, respectively.

Example

The example shows the software bus being used as an asynchronous control signal to select a filter cutoff. It assumes that an external program that has access to the API is feeding the values.

        sr = 44100
        ksmps = 100
        nchnls = 1

        chn_k "cutoff", 1, 3, 1000, 500, 2000

        instr   1
           kc   chnget    "cutoff"
           a1   oscil     p4, p5, 100
           a2   lowpass2  a1, kc, 200
                out       a2
        endin
      

Credits

Author: Istvan Varga
2005