


                              - 6 -





                   2. SYNTAX OF THE ORCHESTRA





     An orchestra statement in Csound has the format:
      label:   result    opcode    argument1, argument2,...     ;comments
The label is optional and identifies  the  basic  statement  that
follows as the potential target of a go-to operation (see Program
Control Statements).  A label has no effect on the statement  per
se.

Comments are optional and are for the purpose of letting the user
document  his orchestra code.  Comments always begin with a semi-
colon (;) and extend to the end of the line.

The remainder (result, opcode,  and  arguments)  form  the  basic
statement.   This  also  is optional, i.e. a line may have only a
label or comment or be entirely blank.   If  present,  the  basic
statement  must  be  complete on one line.  The opcode determines
the operation to be performed; it usually takes  some  number  of
input values (arguments); and it usually has a result field vari-
able to which it sends output values at some fixed  rate.   There
are four possible rates:
      1) once only, at orchestra setup time (effectively a permanent assignment);
      2) once at the beginning of each note (at initialization (init) time:  I-rate);
      3) once every performance-time control loop (perf time control rate, or K-rate);
      4) once each sound sample of every control loop (perf time audio rate, or A-rate).


STATEMENT TYPES

An orchestra program in Csound is comprised of  orchestra  header
statements  which  set  various  global parameters, followed by a
number of instrument  blocks  representing  different  instrument
types.   An  instrument  block, in turn, is comprised of ordinary
statements that set values, control the logical flow,  or  invoke
the various signal processing subroutines that lead to audio out-
put.

An orchestra header statement operates once  only,  at  orchestra
setup time.  It is most commonly an assignment of some value to a
global reserved symbol, e.g.  sr = 20000.  All  orchestra  header
statements belong to a pseudo instrument 0, an init pass of which
is run prior to all other instruments at score time 0.  Any ordi-
nary  statement  can  serve as an orchestra header statement, eg.
gifreq = cpspch(8.09), provided it is an  init-time  only  opera-
tion.

An ordinary statement runs at either  init  time  or  performance
time  or both.  Operations which produce a result formally run at


                        February 20, 1991





                              - 7 -


the rate of that  result  (that  is,  at  init  time  for  I-rate
results; at performance time for K- and A-rate results), with the
sole exception of the init opcode (q.v.).   Most  generators  and
modifiers,  however,  produce signals that depend not only on the
instantaneous value of their arguments but also on some preserved
internal  state.   These performance-time units therefore have an
implicit init-time component to set up that state.  The run  time
of  an  operation  which  produces  no  result is apparent in the
opcode.

Arguments are values that are sent to an operation.   Most  argu-
ments  will  accept arithmetic expressions composed of constants,
variables, reserved globals, value converters, arithmetic  opera-
tions and conditional values; these are described below.











































                        February 20, 1991





                              - 8 -


CONSTANTS AND VARIABLES

constants are floating point numbers,  such  as  1,  3.14159,  or
-73.45  .   They  are available continuously and do not change in
value.

variables are named cells containing numbers.  They are available
continuously  and  may be updated at one of the four update rates
(setup only, I-rate, K-rate, or A-rate).  I- and K-rate variables
are  scalars (i.e. they take on only one value at any given time)
and are primarily used to store and recall controlling data, that
is,  data  that  changes at the note rate (for I-variables) or at
the control rate  (for  K-variables).   I-  and  K-variables  are
therefore  useful  for  storing  note  parameter values, pitches,
durations, slow-moving frequencies, vibratos, etc.   A-variables,
on  the other hand, are arrays or vectors of information.  Though
renewed on the same perf-time control pass as K-variables,  these
array  cells represent a finer resolution of time by dividing the
control  period  into  sample  periods  (see  ksmps  below).   A-
variables are used to store and recall data changing at the audio
sampling rate  (e.g.  output  signals  of  oscillators,  filters,
etc.).

A further distinction is that between local and global variables.
local  variables are private to a particular instrument, and can-
not be read from or written into by any other instrument.   Their
values are preserved, and they may carry information from pass to
pass (e.g. from initialization time to performance time) within a
single instrument.  Local variable names begin with the letter p,
i, k, or a.  The same local variable name may appear  in  two  or
more different instrument blocks without conflict.

global variables are cells that are  accessible  by  all  instru-
ments.   The  names  are  either like local names preceded by the
letter g, or are special reserved symbols.  Global variables  are
used  for  broadcasting general values, for communicating between
instruments (semaphores), or for sending sound from  one  instru-
ment to another (e.g. mixing prior to reverberation).

Given these distinctions, there are eight forms of local and glo-
bal variables:
      type        when renewable          Local       Global
reserved symbols        permanent         --          rsymbol
score parameter fields  I-time                  pnumber     --
init variables          I-time                  iname       giname
control signals         P-time, K-rate          kname       gkname
audio signals           P-time, A-rate          aname       ganame
where rsymbol is a special reserved symbol (e.g. sr, kr),  number
is  a positive integer referring to a score statement pfield, and
name is a string of letters and/or digits with  local  or  global
meaning.   As  might  be  inferred, score parameters are local I-
variables whose values are copied from the invoking score  state-
ment just prior to the Init pass through an instrument.




                        February 20, 1991





                              - 9 -


VALUE CONVERTERS:

                  ftlen(x)         (init-rate args only)

                  int(x)           (init- or control-rate args only)
                  frac(x)           "           "
                  dbamp(x)    "           "

                  i(x)       (control-rate args only)

                  abs(x)           (no rate restriction)
                  exp(x)            "           "
                  log(x)            "           "
                  sqrt(x)           "           "
                  sin(x)            "           "
                  cos(x)            "           "
                  ampdb(x)    "           "
where the argument within the parentheses may be an expression.

Value converters perform arithmetic translation from units of one
kind  to  units  of  another.  The result can then be a term in a
further expression.

ftlen(x)          returns the size  (no.  of  points)  of  stored
function table no. x.

int(x)            "     "  integer part of x.

frac(x)           "     "  fractional part of x.

dbamp(x)    "     "  decibel equivalent of the raw amplitude x.

i(x)        "     an Init-type equivalent of the  argument,  thus
permitting a K-time value
                  to be accessed in at init-time or  reinit-time,
whenever valid.

abs(x)            "     the absolute value of x.

exp(x)            "     e  raised to the xth power.

log(x)            "     the natural log of x (x positive only).

sqrt(x)           "     "  square root of x  (x non-negative).

sin(x)            "     "  sine of x (x in radians).

cos(x)            "     "  cosine of x (x in radians).

ampdb(x)    "     "  amplitude equivalent of the decibel value x.
                  Thus 60 db gives 1000, 66 db gives 2000, 72  db
gives 4000,
                  78 db gives 8000, 84 db gives 16000 and  90  db
gives 32000.



                        February 20, 1991





                             - 10 -


Note that for log, sqrt, and ftlen the  argument  value  is  res-
tricted.

Note also that ftlen will always return a power-of-2 value,  i.e.
the function table guard point (see F statement) is not included.




















































                        February 20, 1991





                             - 11 -


PITCH CONVERTERS

                  octpch(pch) (init- or control-rate args only)
                  pchoct(oct)    "        "
                  cpspch(pch)    "        "
                  octcps(cps)    "        "
                  cpsoct(oct) (no rate restriction)
where the argument  within  the  parentheses  may  be  a  further
expression.

These are really value converters  with  a  special  function  of
manipulating pitch data.

Data concerning pitch and frequency can exist in any of the  fol-
lowing forms:

      name                          abbreviation
      octave point pitch-class (8ve.pc)         pch
      octave point decimal                oct
      cycles per second                   cps

The first two forms  consist  of  a  whole  number,  representing
octave  registration,  followed  by a specially interpreted frac-
tional part.  For pch the fraction is read as two decimal  digits
representing  the  12 equal-tempered pitch classes from .00 for C
to .11 for B.  For oct, the fraction is  interpreted  as  a  true
decimal  fractional  part of an octave.  The two fractional forms
are thus related by the factor 100/12.  In both forms, the  frac-
tion  is  preceded  by a whole number octave index such that 8.00
represents Middle C, 9.00 the C above, etc.   Thus  A440  can  be
represented  alternatively  by 440 (cps), 8.09 (pch), 8.75 (oct),
or 7.21 (pch), etc.  Microtonal divisions of the pch semitone can
be encoded by using more than two decimal places.

The mnemonics of the pitch conversion units are derived from mor-
phemes  of the forms involved, the second morpheme describing the
source and the first morpheme the object (result).  Thus

                  cpspch(8.09)

will convert the pitch argument 8.09 to  its  c.p.s.  (or  hertz)
equivalent,  giving the value of 440.  Since the argument is con-
stant over the duration of the note, this  conversion  will  take
place at I-time, before any samples for the current note are pro-
duced.  By contrast, the conversion

                  cpsoct(8.75 + K1)

which gives the value of A440 transposed by the  octave  interval
K1,  will repeat the calculation every K-period since that is the
rate at which K1 varies.
N.B.  The conversion from pch or oct into cps  is  not  a  linear
operation  but involves an exponential process which may be time-
consuming if executed  repeatedly  at  audio  rates.   Audio-rate
arguments   within  cpsoct  are  permitted  but  should  be  used


                        February 20, 1991





                             - 12 -


sparingly.
























































                        February 20, 1991





                             - 13 -


ARITHMETIC OPERATIONS:
                  -a
                  +a
                  a && b      (logical AND; not audio-rate)
                  a || b      (logical OR; not audio-rate)
                  a + b
                  a - b
                  a * b
                  a / b

where the arguments a and b may be further expressions.

Arithmetic operators perform operations of change-sign  (negate),
don't-change-sign, logical AND, logical OR, add, subtract, multi-
ply and divide.  Note that a value  or  an  expression  may  fall
between  two of these operators, either of which could take it as
its left or right argument, as in
                  a + b * c.

In such cases three rules apply:
  1) * and / bind to their neighbors more strongly than + and -.
   Thus the above expression is taken as
               a + (b * c),
   with * taking b and c and then + taking a and b*c.
  2) + and - bind  more  strongly  than  &&,  which  in  turn  is
  stronger than ||:
               a && b - c || d    is taken as    (a && (b  -  c))
   || d
  3) When both operators bind equally strongly,
   the operations are done left to right:
               a - b - c    is taken as   (a - b) - c.
Parentheses may be used as above to force particular groupings.


CONDITIONAL VALUES:
                  (a >  b ? v1 : v2)
                  (a <  b ? v1 : v2)
                  (a >= b ? v1 : v2)
                  (a <= b ? v1 : v2)
                  (a ==  b ? v1 : v2)
                  (a != b ? v1 : v2)
where a, b, v1 and v2 may be expressions, but  a,  b  not  audio-
rate.

In the above conditionals, a and b are first  compared.   If  the
indicated  relation  is  true (a greater than b, a less than b, a
greater than or equal to b, a less than or equal to b, a equal to
b,  a  not  equal  to b), then the conditional expression has the
value of v1; if the relation is false,  the  expression  has  the
value  of  v2.   (For  convenience,  a  sole '=' will function as
'=='.)
N.B.: If v1 or v2 are expressions, these will be evaluated before
the conditional is determined.

In terms of binding strength, all  conditional  operators  (i.e.,


                        February 20, 1991





                             - 14 -


the  relational  operators  (>, <, etc.), and ? and :) are weaker
than the arithmetic and logical operators (+ , - , *, /,  &&  and
||).

Example:
            (k1 < p5/2 + p6 ?  k1 : p7)

binds the terms p5/2 and p6.  It will return the value  k1  below
this threshold, else the value p7.
















































                        February 20, 1991





                             - 15 -


EXPRESSIONS:

Expressions may be composed to  any  depth  from  the  components
shown above.

Each sub-expression (part of an expression) is evaluated  at  its
own  proper  rate.   For  instance,  if  the  terms within a sub-
expression all change at the control rate  or  slower,  the  sub-
expression  will  be  evaluated  only  at  the control rate; that
result might then be used in an audio-rate evaluation.

Examples:

      k1 + abs(p5/2 + sqrt(k2))
      int(p5) + frac(p5) * 100/12

The above are legal expressions.  They may be placed in unit gen-
erator  argument  positions or be part of an assignment statement
(q.v.).



STATEMENT TYPES:

There are nine statement types, each of which provides a  heading
for the descriptive sections that follow in this document:

      assignment statements
      orchestra header statements
      instrument block statements
      program control statements
      duration control statements
      signal generator statements
      signal modifier statements
      signal display statements
      soundfile access statements



INTERPRETIVE NOTE:

Throughout this document, opcodes are indicated in  boldface  and
their  argument and result mnemonics, when mentioned in the text,
are given in italics.   Argument  names  are  generally  mnemonic
(amp,  phs),  and  the  result is denoted the letter r.  Both are
preceded by a type qualifier i, k, a or x (e.g. kamp, iphs,  ar).
The  prefix i denotes scalar values valid at note Init time; pre-
fixes k or a denote control (scalar) and audio  (vector)  values,
modified and referenced continuously throughout performance (i.e.
at every control period while the instrument is  active).   Argu-
ments are used at the prefix-listed times; results are created at
their listed times, then remain available for use as inputs else-
where.  The validity of inputs is defined by the following:
    arguments with prefix i must be valid at Init time;
    arguments with prefix k can be either control or Init  values


                        February 20, 1991





                             - 16 -


    (which remain valid);
    arguments with prefix a must be vector inputs;
    arguments with prefix x may be either vector or  scalar  (the
    compiler will distinguish).
All arguments, unless otherwise stated, can be expressions  whose
results conform to the above.

Most opcodes (such as linen and oscil) can be used in  more  than
one  mode, which one being determined by the prefix of the result
symbol.















































                        February 20, 1991





                             - 17 -


ASSIGNMENT STATEMENTS

            ir    =     iarg
            kr    =     karg
            ar    =     xarg
            kr    init  iarg
            ar    init  iarg
            ir    tival
            ir    divz  ia, ib, isubst    (these not yet implemented)
            kr    divz  ka, kb, ksubst
            ar    divz  xa, xb, ksubst




= (simple assignment) - Put the  value  of  the  expression  iarg
(karg,  xarg)  into  the  named result.  This provides a means of
saving an evaluated result for later use.

init - Put the value of the I-time expression iarg into a  K-  or
A-variable, i.e., initialize the result.  Note that init provides
the only case of an Init-time statement being permitted to  write
into a Perf-time (K- or A-rate) result cell; the statement has no
effect at Perf-time.

tival - Put the value of the instrument's internal "tie-in"  flag
into  the  named  I-variable.   Assigns  1  if this note has been
'tied' onto a previously held note (see I Statement);  assigns  0
if no tie actually took place.  (See also tigoto.)

divz - Whenever b is not zero, set the result  to  the  value  of
a/b; when b is zero, set it to the value of subst instead.




Example:


      kcps    =   i2/3 + cpsoct(k2 + octpch(p5))

















                        February 20, 1991





                             - 18 -


ORCHESTRA HEADER STATEMENTS


            sr = n1
            kr = n2
            ksmps = n3
            nchnls = n4


These statements are global value assignments, made at the begin-
ning  of  an  orchestra,  before any instrument block is defined.
Their function is to set certain reserved symbol  variables  that
are  required  for performance.  Once set, these reserved symbols
can be used in expressions anywhere in the orchestra.

sr= (optional) - set sampling rate to n1 samples per  second  per
channel.  The default value is 10000.

kr= (optional) - set control rate to n2 samples per second.   The
default value is 1000.

ksmps= (optional) - set  the  number  of  samples  in  a  Control
Period.  This value must equal sr/kr.  The default value is 10.

nchnls= (optional) - set number of channels of  audio  output  to
n4.  (1 = mono, 2 = stereo, 4 = quadraphonic.)  The default value
is 1 (mono).



In addition, any global variable can be initialized by  an  init-
time assignment anywhere before the first instr statement.



All of the above assignments are  run  as  instrument  0  (i-pass
only) at the start of real performance.


Example of header assignments:

      sr = 10000
      kr = 500
      ksmps = 20

gi1   =     sr / 2.
ga1   init  0
gitranspose  =    octpch(.01)









                        February 20, 1991





                             - 19 -


INSTRUMENT BLOCK STATEMENTS

            instr   i, j, ...
            .
            .  <body
            .    of
            .   instrument>
            .
            endin


These statements delimit an instrument block.  They  must  always
occur in pairs.



instr - begin an instrument block defining instruments i, j, ...

i, j, ... must be numbers, not expressions.  Any positive integer
is legal, and in any order, but excessively high numbers are best
avoided.


endin - end the current instrument block.




Note:

There may be any number of instrument blocks in an orchestra.

Instruments can be defined in any order (but they will always  be
both  initialized  and  performed  in ascending instrument number
order).

Instrument blocks cannot be nested (i.e. one block cannot contain
another).



















                        February 20, 1991





                             - 20 -


PROGRAM CONTROL STATEMENTS

            igoto label
            tigoto      label
            kgoto label
            goto  label
            if    ia R ib igoto label
            if    ka R kb kgoto label
            if    ia R ib goto label
            timout      istrt, idur, label
where label is in the same instrument block and is not an expres-
sion,  and  where R is one of the Relational operators (>, <, >=,
<=, ==, !=) (and = for convenience, see  also  under  Conditional
values).

These statements are used to control the order  in  which  state-
ments  in  an instrument block are to be executed.  I-time and P-
time passes can be controlled separately as follows:


igoto - During the I-time  pass  only,  unconditionally  transfer
control to the statement labeled by label.

tigoto - similar to igoto, but effective only  during  an  I-time
pass  at  which a new note is being 'tied' onto a previously held
note (see I Statement); no-op when a tie  has  not  taken  place.
Allows an instrument to skip initialization of units according to
whether a proposed tie was in fact successful  (see  also  tival,
delay).

kgoto - During the P-time passes only,  unconditionally  transfer
control to the statement labeled by label.

goto - (combination of igoto and kgoto) Transfer control to label
on every pass.

if...igoto - conditional branch at I-time, depending on the truth
value  of  the logical expression "ia R ib".  The branch is taken
only if the result is true.

if...kgoto - conditional branch during P-time, depending  on  the
truth  value  of the logical expression "ka R kb".  The branch is
taken only if the result is true.

if...goto - combination of the above.  Condition tested on  every
pass.

timout - conditional branch during P-time, depending  on  elapsed
note  time.   istrt and idur specify time in seconds.  The branch
to label will become effective at time istrt, and will remain  so
for just idur seconds.  Note that timout can be reinitialized for
multiple activation within a single note (see example next page).





                        February 20, 1991





                             - 21 -


Example:

            if   k3 > p5+10 kgoto next






















































                        February 20, 1991





                             - 22 -


            reinit      label
            rigoto      label
            rireturn


These statements permit an instrument to reinitialize itself dur-
ing performance.




reinit - whenever this statement is encountered during  a  P-time
pass,  performance  is temporarily suspended while a special Ini-
tialization pass, beginning at label and continuing  to  rireturn
or  endin,  is  executed.   Performance will then be resumed from
where it left off.

rigoto - similar to igoto, but effective  only  during  a  reinit
pass  (i.e., No-op at standard I-time).  This statement is useful
for bypassing units that are not to be reinitialized.

rireturn - terminates a reinit pass (i.e., No-op at  standard  I-
time).   This  statement,  or an endin, will cause normal perfor-
mance to be resumed.






Example:

The following statements will  generate  an  exponential  control
signal  whose  value moves from 440 to 880 exactly ten times over
the duration p3.


reset:            timout        0, p3/10, contin      ;after p3/10 seconds,
            reinit        reset                 ;  reinit both timout
contin:     k1    expon   440, p3/10, 880       ;  and expon
            rireturn                      ;  then resume perf
















                        February 20, 1991





                             - 23 -


DURATION CONTROL STATEMENTS

            ihold
            turnoff


These statements permit the current note to modify its own  dura-
tion.



ihold - this I-time statement causes a  finite-duration  note  to
become  a 'held' note.  It thus has the same effect as a negative
p3 (see Score I-statement), except that p3 here remains  positive
and  the  instrument  reclassifies  itself to being held indefin-
itely.  The note can be turned off explicitly  with  turnoff,  or
its  space  taken  over  by  another  note of the same instrument
number (i.e. it is tied into that  note).   Effective  at  I-time
only; no-op during a reinit pass.

turnoff - this P-time statement enables  an  instrument  to  turn
itself  off.   Whether  of  finite  duration  or 'held', the note
currently being  performed  by  this  instrument  is  immediately
removed from the active note list.  No other notes are affected.






Example:


The following statements will cause a note to  terminate  when  a
control  signal passes a certain threshold (here the Nyquist fre-
quency).

      k1    expon 440, p3/10, 880         ;begin gliss and continue
            if    k1 < sr/2 kgoto contin  ;  until Nyquist detected
            turnoff                       ;  then quit
contin:     a1    oscil a1, k1, 1
















                        February 20, 1991





                             - 24 -


SIGNAL GENERATORS

      kr    line  ia, idur1, ib
      ar    line  ia, idur1, ib
      kr    expon ia, idur1, ib
      ar    expon ia, idur1, ib
      kr    linseg      ia, idur1, ib[, idur2, ic[...]]
      ar    linseg      ia, idur1, ib[, idur2, ic[...]]
      kr    expseg      ia, idur1, ib[, idur2, ic[...]]
      ar    expseg      ia, idur1, ib[, idur2, ic[...]]

Output values kr or ar trace a straight line (exponential  curve)
or  a  series  of  line  segments  (exponential segments) between
specified points.


INITIALIZATION

ia - starting value.  Zero is illegal for exponentials.

ib, ic, etc.  - value after dur1 seconds, etc.  For exponentials,
must be non-zero and must agree in sign with ia.

idur1 - duration in seconds of first segment.  A zero or negative
value will cause all initialization to be skipped.

idur2, idur3, etc.  - duration in seconds of subsequent segments.
A  zero  or negative value will terminate the initialization pro-
cess with the preceding point, permitting the  last-defined  line
or  curve  to  be  continued  indefinitely  in  performance.  The
default is zero.


PERFORMANCE

These units generate control or audio signals  whose  values  can
pass  through  2 or more specified points.  The sum of dur values
may or may  not  equal  the  instrument's  performance  time:   a
shorter  performance will truncate the specified pattern, while a
longer one will cause the last-defined segment to continue on  in
the same direction.



Example:

      k2    expseg      440, p3/2, 880, p3/2, 440


This statement creates a control signal which moves exponentially
from 440 to 880 and back, over the duration p3.






                        February 20, 1991





                             - 25 -


      kr    phasor      kcps[, iphs]
      ar    phasor      xcps[, iphs]

Produce a normalized moving phase value.


INITIALIZATION

iphs (optional) - initial phase, expressed as  a  fraction  of  a
cycle (0 to 1).  A negative value will cause phase initialization
to be skipped.  The default value is zero.


PERFORMANCE

An internal phase is successively accumulated in accordance  with
the  cps frequency to produce a moving phase value, normalized to
lie in the range 0.<= phs < 1.

When used as the index to a table unit, this phase (multiplied by
the  desired  function table length) will cause it to behave like
an oscillator.

Note that phasor is a special kind  of  integrator,  accumulating
phase increments that represent frequency settings.





Example:

      k1    phasor      1                 ;cycle once per second
      kpch  table k1*12, 1          ;through 12-note pch table
      a1    oscil p4, cpspch(kpch), 2     ;with continuous sound






















                        February 20, 1991





                             - 26 -


      ir    table indx, ifn[, ixmode][, ixoff][, iwrap]
      ir    tablei      indx, ifn[, ixmode][, ixoff][, iwrap]
      kr    table kndx, ifn[, ixmode][, ixoff][, iwrap]
      kr    tablei      kndx, ifn[, ixmode][, ixoff][, iwrap]
      ar    table andx, ifn[, ixmode][, ixoff][, iwrap]
      ar    tablei      andx, ifn[, ixmode][, ixoff][, iwrap]
      kr    oscil1      idel, kamp, idur, ifn
      kr    oscil1i     idel, kamp, idur, ifn

Table values are accessed by direct indexing  or  by  incremental
sampling.

INITIALIZATION

ifn  -  function  table  number.   tablei,  oscil1i  require  the
extended guard point.

ixmode (optional) - ndx data mode. 0 = raw ndx, 1 = normalized (0
to 1).  The default value is 0.

ixoff (optional) - amount by which ndx is to be  offset.   For  a
table with origin at center, use tablesize/2 (raw) or .5 (normal-
ized).  The default value is 0.

iwrap (optional) -  wraparound  ndx  flag.   0  =  nowrap  (ndx<0
treated  as  ndx=0;  ndx>tablesize  sticks at ndx=size), 1 = wra-
paround.  The default value is 0.

idel -  delay  in  seconds  before  oscil1  incremental  sampling
begins.

idur - duration in seconds to sample  through  the  oscil1  table
just  once.   A zero or negative value will cause all initializa-
tion to be skipped.


PERFORMANCE

table invokes table lookup on behalf of init,  control  or  audio
indices.   These indices can be raw entry numbers (0,1,2...siz-1)
or scaled values (0 to 1-e).  Indices are first modified  by  the
offset  value  then  checked  for  range before table lookup (see
iwrap).  If ndx is likely to be full scale, or  if  interpolation
is  being  used,  the  table should have an extended guard point.
table indexed by a periodic phasor (see phsor) will  simulate  an
oscillator.

oscil1 accesses values by  sampling  once  through  the  function
table  at a rate determined by idur.  For the first idel seconds,
the point of scan will reside at the first location of the table;
it  will  then begin moving through the table at a constant rate,
reaching the end in another idur seconds; from that time on (i.e.
after  idel  +  idur seconds) it will remain pointing at the last
location.  Each value obtained from sampling is  then  multiplied
by an amplitude factor kamp before being written into the result.


                        February 20, 1991





                             - 27 -


tablei and oscil1i are interpolating units  in  which  the  frac-
tional  part of ndx is used to interpolate between adjacent table
entries.  The smoothness gained by interpolation is at some small
cost  in execution time (see also oscili, etc.), but the interpo-
lating and non-interpolating units are otherwise  interchangable.
Note  that  when  tablei  uses a periodic index whose modulo n is
less than the power of 2 table length, the interpolation  process
requires that there be an (n+1)th table value that is a repeat of
the 1st (see F statement in Score).
















































                        February 20, 1991





                             - 28 -


      kr    oscil kamp, kcps, ifn[, iphs]
      kr    oscili      kamp, kcps, ifn[, iphs]
      ar    oscil xamp, xcps, ifn[, iphs]
      ar    oscili      xamp, xcps, ifn[, iphs]
      ar    foscil      xamp, kcps, kcar, kmod, kndx, ifn[, iphs]
      ar    foscili     xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

Table ifn is incrementally sampled modulo the  table  length  and
the value obtained is multiplied by amp.


INITIALIZATION

ifn - function table number.  Requires a wrap-around guard point.

iphs (optional) - initial phase of sampling, expressed as a frac-
tion of a cycle (0 to 1).  A negative value will cause phase ini-
tialization to be skipped.  The default value is 0.


PERFORMANCE

The oscil units output periodic control (or audio)  signals  con-
sisting of the  value of kamp(xamp) times the value returned from
control rate (audio rate) sampling of a  stored  function  table.
The  internal   phase  is  simultaneously  advanced in accordance
with the cps input value.   While  the  amplitude  and  frequency
inputs  to  the  K-rate oscils are scalar only, the corresponding
inputs to the audio-rate oscils may each be either scalar or vec-
tor, thus permitting amplitude and frequency modulation at either
sub-audio or audio frequencies.

foscil is a composite unit that effectively banks two  oscils  in
the  familiar Chowning FM setup, wherein the audio-rate output of
one generator is used to modulate the frequency input of  another
(the  "carrier").   Effective  carrier frequency = kcps*kcar, and
modulating frequency = kcps*kmod.  For integral  values  of  kcar
and  kmod, the perceived fundamental will be the minimum positive
value of kcps * (kcar - n*kmod), n = 0,1,2,...  The input kndx is
the  index of modulation (usually time-varying and ranging 0 to 4
or so) which determines the spread of acoustic  energy  over  the
partial positions given by n = 0,1,2,..,etc.  ifn should point to
a stored sine wave.

oscili and foscili differ from oscil and foscil  respectively  in
that  the standard procedure of using a truncated phase as a sam-
pling index is here replaced  by  a  process  that   interpolates
between  two  successive  lookups.  Interpolating generators will
produce a noticeably cleaner output signal, but they may take  as
much  as  twice  as  long  to run.  Adequate accuracy can also be
gained without the time cost  of  interpolation  by  using  large
stored  function  tables  of  2K, 4K or 8K points if the space is
available.

Example:


                        February 20, 1991





                             - 29 -


      k1    oscil 10, 5, 1                ;5 cps vibrato
      a1    oscil 5000, 440+k1, 1         ;around A440 +-10 cps























































                        February 20, 1991





                             - 30 -


      ar    buzz  xamp, xcps, knh, ifn[, iphs]
      ar    gbuzz xamp, xcps, knh, klh, kr, ifn[, iphs]

Output is a set of harmonically related cosine partials.


INITIALIZATION

ifn - table number of a stored function containing (for  buzz)  a
sine  wave, or (for gbuzz) a cosine wave.  In either case a large
table of at least 8192 points is recommended.

iphs (optional) - initial phase  of  the  fundamental  frequency,
expressed  as  a  fraction of a cycle (0 to 1).  A negative value
will cause phase initialization to be skipped.  The default value
is zero.


PERFORMANCE

These units generate an  additive  set  of  harmonically  related
cosine  partials  of fundamental frequency xcps, and whose ampli-
tudes are scaled so their summation peak equals xamp.  The selec-
tion and strength of partials is determined by the following con-
trol parameters:

knh - total number of harmonics requested.  Must be positive.

klh - lowest harmonic present.  Can be positive,  zero  or  nega-
tive.   In  gbuzz  the  set  of partials can begin at any partial
number and proceeds upwards;  if klh is  negative,  all  partials
below zero will reflect as positive partials without phase change
(since cosine is an even function), and will  add  constructively
to any positive partials in the set.

kr - specifies the multiplier in the series of amplitude  coeffi-
cients.   This  is  a  power  series:  if the klhth partial has a
strength coefficient of A, the  (klh+n)th  partial  will  have  a
coefficient  of  A  *  (kr**n),  i.e.   strength  values trace an
exponential curve.  kr may be positive, zero or negative, and  is
not restricted to integers.

buzz and gbuzz are useful as complex sound sources in subtractive
synthesis.   buzz  is a special case of the more general gbuzz in
which klh = kr = 1; it thus produces a set of knh  equal-strength
harmonic  partials,  beginning  with the fundamental.  (This is a
band-limited pulse train; if the partials extend to the  Nyquist,
i.e.   knh  =  int(sr/2/fundamental  freq.), the result is a real
pulse train of amplitude xamp.) Although both knh and klh may  be
varied  during performance, their internal values are necessarily
integer and may cause "pops" due to discontinuities in  the  out-
put;  kr,  however,  can  be  varied  during  performance to good
effect.  Both buzz and gbuzz can be amplitude- and/or  frequency-
modulated by either control or audio signals.



                        February 20, 1991





                             - 31 -


N.B.  These two units have their analogs in GEN11, in  which  the
same  set  of  cosines can be stored in a function table for sam-
pling by an oscillator.  Although computationally more efficient,
the  stored pulse train has a fixed spectral content, not a time-
varying one as above.




















































                        February 20, 1991





                             - 32 -


      ar    adsyn       kamod, kfmod, ifilno
      ar    pvoc        ktimpnt, kfmod, ispecwp, ifilno

Output is an additive set of individually  controlled  sinusoids,
using either an oscillator bank or phase vocoder resynthesis.


INITIALIZATION

ispecwp - if non-zero, attempts to preserve the spectral envelope
while its frequency content is varied by kfmod.

ifilno - control-file suffix (m)  of  a  file  named  adsyn.m  or
pvoc.m, stemming from analysis of an audio signal.  adsyn control
contains  breakpoint  amplitude-  and  frequency-envelope  values
organized for oscillator resynthesis, while pvoc control contains
similar data organized for fft  resynthesis.   Note  that  memory
usage  depends  on  the size of the control files involved, which
are stored internally during computation.


PERFORMANCE

adsyn synthesizes complex time-varying timbres through the method
of  additive  synthesis.  Any number of sinusoids, each individu-
ally controlled in frequency and  amplitude,  can  be  summed  by
high-speed arithmetic to produce a high-fidelity result.

Component sinusoids are  described  by  a  control  file  (format
described  elsewhere) that specifies both frequency and amplitude
tracks in  breakpoint  fashion  (to  the  millisecond).   Through
interpolation,  the  instantaneous frequency and amplitude values
are used by an internal fixed-point  oscillator  that  adds  each
active  partial  into an accumulated output signal.  There are no
limits on the  number  of  contributing  partials,  or  on  their
behavior  over  time.  Any sound complex that can be described in
terms of the behavior of sinusoids can be  synthesized  by  adsyn
alone.

In addition, the sound described by the control file can be modi-
fied  during  actual  synthesis.   The signals kamod, kfmod, will
modify the amplitude and frequency, respectively, of each contri-
buting  partial.   Note  that these are multiplying factors, with
kfmod being applied to the cps frequency.  Thus the values .7,1.5
will  give  rise  to  a softer sound, a perfect fifth higher; the
values 1,1 will leave the sound unmodified.  Each of these inputs
can be a control signal.

pvoc implements signal reconstruction using  an  fft-based  phase
vocoder.  The control data stems from a precomputed analysis file
with a known frame rate.  The passage of time through  this  file
is  specified  by  ktimpnt, which represents the time in seconds.
ktimpnt must always be positive, but can move forwards  or  back-
wards  in time, be stationary or discontinuous, as a pointer into
the analysis file.  kfmod is a control-rate transposition factor:


                        February 20, 1991





                             - 33 -


a value of 1 incurs no transposition, 1.5 transposes up a perfect
fifth, and .5 down an octave.

This implementation of pvoc was written  by  Dan  Ellis.   It  is
based  in part on the system of Mark Dolson, but the pre-analysis
concept is new.



















































                        February 20, 1991





                             - 34 -


      ar    fof   xamp,  xfund,  xforma,  xformb,  koct,  ktex,  kband,  kdebat, katt,
                              iolaps,  ifna,  ifnb,  idur[, iphs][,  icor]

Audio output is a succession of FOF impulses.  With  xfund  above
c.  30  Hz  these  produce a formant (set of harmonically related
partials whose spectral envelope can  be  controlled  by  k-input
parameters).   With  lower fundamentals this generator provides a
special form of granular synthesis.

INITIALIZATION

iolaps  - the maximum number of  overlapping  FOFs  in  the  note
event.  May be calculated as the maximum value of xfund * (kdebat
+ katt), rounded up to an integer.  Too small a value will result
in a warning message;  the program will continue to run with pos-
sible distortion.  An excessively large value will waste computa-
tion time.

ifna, ifnb - table numbers of  stored  functions.  Normally  both
will  reference the same sine wave table. As interpolation is not
used in the table lookup a table of at least 8192 is recommended.

idur - normally set to "p3" (the note length). A FOF impulse can-
not  be  created  unless  it  can complete its course before time
idur.

iphs (optional) - initial phase (of the fundamental) expressed as
a fraction of a cycle (0 to 1).  The default value is 0.

icor (optional) - automatic correction of the spectrum,  allowing
for  ktex and kband.  Normalises the internal amplitude, enabling
xamp to specify the output amp relative to other formant  regions
(i.e. FOF unit-generators).  Accurate only if all generators con-
cerned have the same fundamental frequency.  This is designed  to
work within the normal range of input values for vocal imitation;
its use in other situations may produce strange amplitudes.  1  =
on, 0 = off;  the default is 1.

PERFORMANCE

xamp -  amplitude.  This also varies  with  the  number  of  FOFs
overlapping  (and  with  ktex  and kband if icor is not on).  The
experienced user will learn to adjust xamp accordingly.

xfund - the fundamental frequency (in Hertz).

xforma, xformb - the formant frequency.  Changes to  xforma  only
take  effect  at  the  start of a new FOF; each FOF impulse has a
fixed formant frequency from this input.  xformb allows  continu-
ous change.  The actual formant frequency is the sum of these two
inputs.

ktex   -  attack  time  in  seconds  of  the  FOF  impulse.   The
skirtwidth  of  the formant region (-40dB) varies in inversely to
this.  A common value for vocal imitation is .003 .


                        February 20, 1991





                             - 35 -


kband  - bandwidth of the formant region at -6dB in Hz.

kdebat, katt - the start time (relative to the start of the  FOF)
and  length (in seconds) of the sinusoidal rounding at the end of
each FOF impulse.  Typical values are .01 and .007 .

The fof generator is  written  by  Michael  Clarke  (Huddersfield
Polytechnic,  England)  based  on  the  CHANT  program from IRCAM
(Xavier Rodet et al.).  Each fof generator produces a single for-
mant  region,  and  the  output  of  five or more of these can be
summed to produce a rich vocal imitation.   FOF  synthesis  is  a
special  form  of  granular  synthesis  and  this module has been
specifically designed to facilitate transformations between vocal
(and other) imitation and granular textures.











































                        February 20, 1991





                             - 36 -


      ar    pluck kamp, kcps, icps, ifn, imeth [, iparm1, iparm2]

Audio output is a naturally decaying plucked string or drum sound
based on the Karplus-Strong algorithms.

INITIALIZATION

icps - intended pitch value in cps, used to set up a buffer of  1
cycle  of  audio  samples  which  will be smoothed over time by a
chosen decay method.  icps  normally  anticipates  the  value  of
kcps,  but  may  be set artificially high or low to influence the
size of the sample buffer.

ifn - table number of a stored function used  to  initialize  the
cyclic  decay buffer.  If ifn = 0, a random sequence will be used
instead.

imeth - method of natural decay.  There are six,  some  of  which
use parameters values that follow.
 1 - simple averaging.  A simple smoothing process,  uninfluenced
   by parameter values.
 2  -  stretched  averaging.   As  above,  with  smoothing   time
   stretched by a factor of iparm1 ( >= 1 ).
 3 - simple drum.  The range from pitch to noise is controlled by
   a  'roughness  factor'  in  iparm1  (0  to 1).  Zero gives the
   plucked string effect, while 1 reverses the polarity of  every
   sample  (octave down, odd harmonics).  The setting .5 gives an
   optimum snare drum.
 4 - stretched drum.  Combines both roughness  and  stretch  fac-
   tors.   iparm1  is  roughness (0 to 1), and iparm2 the stretch
   factor ( >= 1 ).
 5 - weighted averaging.  As method 1, with iparm1 weighting  the
   current  sample (the status quo) and iparm2 weighting the pre-
   vious adjacent one.  iparm1 + iparm2 must be <= 1.
 6 - 1st order recursive filter, with coefs  .5.   Unaffected  by
   parameter values.

iparm1, iparm2 (optional) -  parameter  values  for  use  by  the
smoothing algorithms (above).  The default values are both 0.

PERFORMANCE

An internal audio buffer, filled at I-time according to  ifn,  is
continually  resampled  with  periodicity  kcps and the resulting
output is multiplied by kamp.  Parallel with  the  sampling,  the
buffer is smoothed to simulate the effect of natural decay.

Plucked strings (1,2,5,6) are best realized by  starting  with  a
random  noise  source,  which is rich in initial harmonics.  Drum
sounds (methods 3, 4) work best with a flat source (wide  pulse),
which produces a deep noise attack and sharp decay.

The original Karplus-Strong algorithm used a fixed number of sam-
ples  per cycle, which caused serious quantization of the pitches
available and their intonation.  This implementation resamples  a


                        February 20, 1991





                             - 37 -


buffer  at the exact pitch given by kcps, which can be varied for
vibrato and glissando effects.  For low values of the  orch  sam-
pling  rate  (e.g.  sr = 10000), high frequencies will store only
very few samples (sr/icps).   Since  this  may  cause  noticeable
noise  in  the  resampling  process,  the  internal  buffer has a
minimum size of 64 samples.  This can be further enlarged by set-
ting icps to some artificially lower pitch.


















































                        February 20, 1991





                             - 38 -


      kr    rand  xamp[, iseed]
      kr    randh kamp, kcps[, iseed]
      kr    randi kamp, kcps[, iseed]
      ar    rand  xamp[, iseed]
      ar    randh xamp, xcps[, iseed]
      ar    randi xamp, xcps[, iseed]

Output is a controlled random  number  series  between  +amp  and
-amp.


INITIALIZATION

iseed (optional) - seed value  for  the  recursive  psuedo-random
formula.  A value between 0 and +1 will produce an initial output
of  kamp  *  iseed.   A  negative  value  will  cause  seed   re-
initialization to be skipped.  The default seed value is .5 .


PERFORMANCE

The internal psuedo-random formula produces values which are uni-
formly  distributed over the range kamp to -kamp.  rand will thus
generate uniform white noise with an R.M.S value of kamp/root 2.

The remaining units produce band-limited noise: the  cps  parame-
ters permit the user to specify that new random numbers are to be
generated at a rate less than the sampling  or  control  frequen-
cies.   randh  will  hold  each  new number for the period of the
specified cycle; randi will produce  straight-line  interpolation
between each new number and the next.




Example:

      i1    =     octpch(p5)        ;center pitch, to be modified
      k1    randh 1,10              ;10 times/sec by random dis-
                                    ;placements up to 1 octave
      a1    oscil 5000, cpsoct(i1+k1), 1
















                        February 20, 1991





                             - 39 -


SIGNAL MODIFIERS

      kr    linen kamp, irise, idur, idec
      ar    linen xamp, irise, idur, idec
      kr    envlpx      kamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]
      ar    envlpx      xamp, irise, idur, idec, ifn, iatss, iatdec[, ixmod]

linen - apply a straight line rise and decay pattern to an  input
amp signal.
envlpx - apply an envelope consisting of 3  segments:  1)  stored
function  rise  shape,  2)  modified  exponential  "pseudo steady
state", 3) true exponential decay


INITIALIZATION

irise - rise time in seconds.  A zero or negative value signifies
no rise modification.

idur - overall duration in seconds.  A  zero  or  negative  value
will cause all initialization to be skipped.

idec - decay time in seconds.  A zero value  indicates  no  decay
modification.     A  value  greater  than idur will cause a trun-
cated decay pattern.

ifn - function table number of stored rise  shape  with  extended
guard point.

iatss - attenuation factor, by which the  last  value  of  envlpx
rise  pattern  will  become  modified  during  the  note's pseudo
"steady state." A factor >1 will cause an exponential growth, and
a  factor  <1  an exponential decay.  The value 1 will maintain a
true steady state  at  the  last  rise  value.   Note  that  this
attenuation  is  not by fixed rate (as in a piano), but is sensi-
tive to a note's duration.  However, if iatss is negative (or  if
"steady  state"  <  4  k-periods)  a  fixed  attenuation  rate of
abs(iatss) per second will be used.  0 is illegal.

iatdec - attenuation factor by which the closing  "steady  state"
value is to be reduced exponentially over the decay period.  This
value must be positive and will normally be of the order of .01 .
A  large or an excessively small value is apt to produce a cutoff
which is audible.  A zero or neg value is illegal.

ixmod (optional, between +-.9 or so) - exponential  curve  modif-
ier,  influencing  the  "steepness" of the exponential trajectory
during the "steady state."  Values less than zero will  cause  an
accelerated  growth  or  decay  towards  the  target (e.g. subito
piano).  Values greater than zero will cause a retarded growth or
decay.  The default value is zero (unmodified exponential).


PERFORMANCE



                        February 20, 1991





                             - 40 -


Rise-time modifications are applied for the first irise  seconds,
and decay-time modifications from time idur - idec.  If these two
modification periods are separated in time there will be  a  real
"steady state" period during which amp will be unmodified (linen)
or modified by  the  first  exponential  pattern  (envlpx).   For
linen,  if the rise and decay periods overlap then both modifica-
tions will be in effect for that time; for envlpx an overlap will
simply  cause a truncated decay pattern.  If the overall duration
idur is exceeded in performance, the  final  decay  pattern  will
continue  on  in the same direction, going negative for linen but
tending asymptotically to zero in the case of envlpx.














































                        February 20, 1991





                             - 41 -


Examples:




                                          .     .
                /                     `.                         .  .
               /                        `.                         .
              /                           `.                      .  .
             /                              `.                   .  ,.`.
            /                                 `.                . ,`    `.
           /                                    `.             .'         `.
          /                                       `.          /             `.
         /                                          `.       /                `.
        /`/`

        Ex 1.  linen    a) normal,  b) with overlapping rise and decay



                       
                      / `.
                     /    `.
                    /       ` .
                   /            `   .
                  /                    `     .        .         .
             /`  /                                                      `
            /  `/                                                        `.
           /                                                               `.
          /                                                                  `
         /                                                                     ` .
        /`...

        Ex 2.  envlpx   with iatss = .5 and ixmod = 0




                       /`
                      / |
                     /  |
                    /    .
                   /      .
                  /        `- - - - . . .  .   .           
             /`  /                                                     `
            /  `/                                                        `.
           /                                                                `.
          /                                                                    `
         /                                                                        ` .
        /`...

        Ex 3.  envlpx     with iatss = .5 and ixmod = -.9





                        February 20, 1991





                             - 42 -


      kr    port  ksig, ihtim[, isig]
      ar    tone  asig, khp[, istor]
      ar    atone asig, khp[, istor]
      ar    reson asig, kcf, kbw[, iscl, istor]
      ar    areson      asig, kcf, kbw[, iscl, istor]

A control or audio signal is modified  by  a  low-  or  band-pass
recursive filter with variable frequency response.


INITIALIZATION

isig - initial (i.e. previous) value for internal feedback.   The
default value is 0.

istor -  initial  disposition  of  internal  data  space.   Since
filtering  incorporates  a  feedback loop of previous output, the
initial status of the storage space used is significant.  A  zero
value  will clear the space; a non-zero value will allow previous
information to remain.  The default value is 0.

iscl - coded scaling factor for resonators.  A value of 1  signi-
fies  a  peak  response  factor of 1, i.e.  all frequencies other
than kcf are  attenuated  in  accordance  with  the  (normalized)
response  curve.  A value of 2 raises the response factor so that
its overall RMS value equals 1.  (This intended  equalization  of
input  and  ouput  power  assumes  all frequencies are physically
present; hence it is most applicable  to  white  noise.)  A  zero
value  signifies  no  scaling of the signal, leaving that to some
later adjustment (e.g. see balance).  The default value is 0.


PERFORMANCE

port applies portamento to a step-valued control signal.  At each
new  step  value,  ksig is low-pass filtered to move towards that
value at a rate determined by ihtim.  ihtim is the "half-time" of
the  function  (in seconds), during which the curve will traverse
half the distance towards the new value, then half as much again,
etc., theoretically never reaching its asymptote.

tone implements a first-order recursive low-pass filter in  which
the  variable  khp  (in  c.p.s.)  determines the response curve's
half-power point.  Half power is defined as peak power / root 2.

reson is a second-order filter in which kcf controls  the  center
frequency, or cps position of the peak response, and kbw controls
its bandwidth (the cps difference between  the  upper  and  lower
half-power points).

atone, areson are filters whose transfer functions are  the  com-
plements  of  tone  and reson.  atone is thus a form of high-pass
filter  and  areson  a  notch  filter  whose  transfer  functions
represent the "filtered out" apsects of their complements.  Note,
however, that power scaling is not normalized in  atone,  areson,


                        February 20, 1991





                             - 43 -


but  remains the true complement of the corresponding unit.  Thus
an audio signal, filtered by parallel matching reson  and  areson
units, would under addition simply reconstruct the original spec-
trum.  This property is particularly useful for controlled mixing
of different sources (e.g., see lpreson).

Complex response curves such as those with multiple peaks can  be
obtained  by  using  a  bank of suitable filters in series.  (The
resultant response is the product of  the  component  responses.)
In  such  cases, the combined attenuation may result in a serious
loss of signal power, but this can be regained by the use of bal-
ance.













































                        February 20, 1991





                             - 44 -


krmsr,krmso,kerr,kcps   lpread            ktimpnt, ifilno[, inpoles][, ifrmrate]
      ar          lpreson           asig
      ar          lpfreson          asig, kfrqratio

These units, used as a read/reson pair, use  a  control  file  of
time-varying  filter coefficients to dynamically modify the spec-
trum of an audio signal.


INITIALIZATION

ifilno - control-file suffix (m) referring to a file named 'lp.m'
containing  frames  of  reflection  coefficients and four special
parameter values derived from n-pole linear  predictive  spectral
analysis  of  a  source  file.   A negative value will cause file
opening and initialization to be skipped.

inpoles, ifrmrate (optional) - number of poles,  and  frame  rate
per  second  in  the  lpc analysis.  These arguments are required
only when the control file does not  have  a  header;   they  are
ignored when a header is detected.  The default value for both is
zero.


PERFORMANCE

lpread  accesses  a  control  file  of  time-ordered  information
frames,  each  containing n-pole filter coefficients derived from
linear predictive analysis of  a  source  signal  at  fixed  time
intervals (e.g. 1/100 of a second), plus four parameter values:
      krmsr - root-mean-square (rms) of the residual of analysis,
      krmso - rms of the original signal,
      kerr - the normalized error signal,
      kcps - pitch in cps.
lpread gets its values from the control  file  according  to  the
input  value  ktimpnt  (in  seconds).  If ktimpnt proceeds at the
analysis rate, time-normal synthesis will result;  proceeding  at
a  faster,  slower,  or  variable rate will result in time-warped
synthesis.  At each K-period, lpread  automatically  interpolates
between  adjacent frames to more accurately determine the parame-
ter values (presented as output) and the filter coefficient  set-
tings (passed internally to a subsequent lpreson).

The error signal kerr (between 0 and 1) derived during predictive
analysis reflects the deterministic/random nature of the analyzed
source.  This will emerge low for pitched (periodic) material and
higher  for  noisy  material.   The  transition  from  voiced  to
unvoiced speech, for example, produces an error signal  value  of
about  .3.   During synthesis, the error signal value can be used
to determine the nature of the  lpreson  driving  function:   for
example, by arbitrating between pitched and non-pitched input, or
even by determining a mix of the two.  In  normal  speech  resyn-
thesis,  the pitched input to lpreson is a wideband periodic sig-
nal or pulse train derived from a unit  such  as  buzz,  and  the
non-pitched  source  is  usually derived from rand.  However, any


                        February 20, 1991





                             - 45 -


audio signal can be  used  as  the  driving  function,  the  only
assumption of the analysis being that it has a flat response.

lpfreson is a formant shifted lpreson, in which kfrqratio is  the
(cps)  ratio of shifted to original formant positions.  This per-
mits synthesis in which the source object  changes  its  apparent
acoustic  size.   lpfreson  with  kfrqratio  = 1 is equivalent to
lpreson.

Generally, lpreson provides a means whereby the time-varying con-
tent and spectral shaping of a composite audio signal can be con-
trolled by the dynamic spectral content of another.  There can be
any number of lpread/lpreson (or lpfreson) pairs in an instrument
or in an orchestra; they can read from the same or different con-
trol files independently.










































                        February 20, 1991





                             - 46 -


      kr    rms         asig[, ihp, istor]
      ar    gain        asig, krms[, ihp, istor]
      ar    balance           asig, acomp[, ihp, istor]

The rms power of asig can be interrogated, set,  or  adjusted  to
match that of a comparator signal.


INITIALIZATION

ihp (optional) - half-power point (in cps) of a special  internal
low-pass filter.  The default value is 10.

istor (optional) - initial disposition  of  internal  data  space
(see reson).  The default value is 0.


PERFORMANCE

rms output values kr will trace the rms value of the audio  input
asig.   This  unit is not a signal modifier, but functions rather
as a signal power-guage.

gain provides an amplitude modification of asig so that the  out-
put  ar  has rms power equal to krms.  rms and gain used together
(and given matching ihp values) will provide the same  effect  as
balance.

balance outputs a version of asig, amplitude-modified so that its
rms  power  is equal to that of a comparator signal acomp. Thus a
signal that has suffered loss of power (eg., in passing through a
filter  bank)  can be restored by matching it with, for instance,
its own source.  It should be noted that gain and balance provide
amplitude  modification  only - output signals are not altered in
any other respect.



Example:

      asrc  buzz  10000, 440, sr/440, 1   ;band-limited pulse train
      a1    reson asrc, 1000, 100         ;sent through
      a2    reson a1, 3000, 500           ;2 filters
      afin  balance     a2, asrc                ;then balanced with source













                        February 20, 1991





                             - 47 -


      kr    downsamp    asig[, iwlen]
      ar    upsamp      ksig
      ar    interp            ksig[, istor]
      kr    integ       ksig[, istor]
      ar    integ       asig[, istor]
      kr    diff        ksig[, istor]
      ar    diff        asig[, istor]
      kr    samphold    xsig, kgate[, ival, ivstor]
      ar    samphold    asig, xgate[, ival, ivstor]

Modify a signal by up- or down-sampling,  integration,  and  dif-
ferentiation.


INITIALIZATION

iwlen (optional) - window length in samples over which the  audio
signal  is  averaged  to  determine a downsampled value.  Maximum
length is ksmps; 0 and 1 imply no window averaging.  The  default
value is 0.

istor (optional) - initial disposition  of  internal  save  space
(see reson).  The default value is 0.

ival, ivstor (optional) - controls initial disposition of  inter-
nal  save  space.  If ivstor is zero the internal "hold" value is
set to ival; else it retains its previous value.  Defaults are 0,
0 (i.e. init to zero).

PERFORMANCE

downsamp converts an audio signal to a control signal by downsam-
pling.   It produces one kval for each audio control period.  The
optional window invokes a simple  averaging  process  to  supress
foldover.

upsamp, interp convert a control signal to an audio signal.   The
first  does  it  by  simple repetition of the kval, the second by
linear interpolation  between  successive  kvals.   upsamp  is  a
slightly more efficient form of the assignment 'asig = ksig'.

integ, diff perform integration and differentiation on  an  input
control  signal  or  audio  signal.   Each is the converse of the
other, and applying both will reconstruct  the  original  signal.
Since  these  units  are  special cases of low-pass and high-pass
filters, they produce a scaled (and phase shifted) output that is
frequency-dependent.  Thus diff of a sine produces a cosine, with
amplitude 2*sin(pi*cps/sr) that of the original  (for  each  com-
ponent  partial);  integ  will inversely affect the magnitudes of
its component inputs.  With this understanding, these  units  can
provide useful signal modification.

samphold  performs  a  sample-and-hold  operation  on  its  input
according  to  the value of gate.  If gate > 0, the input samples
are passed to the output;  if gate <= 0, the last output value is


                        February 20, 1991





                             - 48 -


repeated.  The controlling gate can be a constant, a control sig-
nal, or an audio signal.

Example:

      asrc  buzz    10000, 440, 20, 1     ;band-limited pulse train
      adif  diff    asrc                  ;emphasize the highs
      anew  balance       adif, asrc            ;   but retain the power
      agate reson   asrc, 0, 440          ;use a lowpass of the original
      asamp samphold  anew, agate         ;   to gate the new audiosig
      aout  tone    asamp, 100            ;smooth out the rough edges














































                        February 20, 1991





                             - 49 -


      ar    delayr      idlt[, istor]
            delayw      asig
      ar    delay asig, idlt[, istor]
      ar    delay1      asig[, istor]

A signal can be read from or written into a delay path, or it can
be automatically delayed by some time interval.


INITIALIZATION

idlt - requested delay time in seconds.  This can be as large  as
available  memory  will permit.  The space required for n seconds
of delay is 4n * sr bytes.  It  is  allocated  at  the  time  the
instrument  is first initialized, and returned to the pool at the
end of a score section.

istor (optional) - initial disposition of delay-loop  data  space
(see reson).  The default value is 0.


PERFORMANCE

delayr reads from  an  automatically  established  digital  delay
line,  in  which  the signal retrieved has been resident for idlt
seconds.  This unit must be paired with and precede an accompany-
ing delayw unit.  Any other Csound statements can intervene.

delayw writes asig into the delay area established by the preced-
ing  delayr  unit.   Viewed as a pair, these two units permit the
formation of modified feedback loops, etc.  However, there  is  a
lower  bound  on the value of idlt, which must be at least 1 con-
trol period (or 1/kr).

delay is a composite of the above two units,  both  reading  from
and  writing  into  its own storage area.  It can thus accomplish
signal time-shift, although modified feedback  is  not  possible.
There is no minimum delay period.

delay1 is a special form of delay that serves to delay the  audio
signal  asig  by  just  one  sample.   It  is  thus  functionally
equivalent to "delay asig,1/srate" but is more efficient in  both
time and space.  This unit is particularly useful in the fabrica-
tion of generalized non-recursive filters.

Example:

            tigoto      contin            ;except on a tie,
      a2    delay a1, .05, 0        ;begin 50 msec clean delay of sig
      contin:







                        February 20, 1991





                             - 50 -


      ar    deltap            kdlt
      ar    deltapi           xdlt

Tap a delay line at variable offset times.



PERFORMANCE

These units can tap into a delayr/delayw pair, extracting delayed
audio  from  the  idlt seconds of stored sound.  There can be any
number of deltap and/or deltapi units between a read/write  pair.
Each receives an audio tap with no change of original amplitude.

deltap extracts sound by reading  the  stored  samples  directly;
deltapi extracts sound by interpolated readout.  By interpolating
between adjacent stored samples deltapi represents  a  particular
delay  time  with  more accuracy, but it will take about twice as
long to run.

The arguments  kdlt,  xdlt  specify  the  tapped  delay  time  in
seconds.   Each can range from 1 Control Period to the full delay
time of the read/write pair;  however, since there is no internal
check  for  adherence to this range, the user is wholly responsi-
ble.  Each argument can be a constant, a  variable,  or  a  time-
varying  signal;  the  xdlt  argument  in deltapi implies that an
audio-varying delay is permitted there.

These units can provide multiple delay taps for  arbitrary  delay
path  and  feedback  networks.  They can deliver either constant-
time or time-varying taps, and are  useful  for  building  chorus
effects,  harmonizers,  and  doppler shifts.  Constant-time delay
taps (and some slowly changing ones)  do  not  need  interpolated
readout;   they  are well served by deltap.  Medium-paced or fast
varying dlt's, however, will need the extra services of deltapi.

N.B.  K-rate delay times are  not  internally  interpolated,  but
rather  lay down stepped time-shifts of audio samples;  this will
be found quite adequate  for  slowly  changing  tap  times.   For
medium  to  fast-paced  changes,  however,  one  should provide a
higher resolution audio-rate timeshift as input.





Example:

      asource     buzz  1, 440, 20, 1
      atime linseg      1, p3/2, .01, p3/2, 1   ;trace a distance in secs
      ampfac      =     1/atime/atime           ;  and calc an amp factor
      adump delayr      1                 ;set maximum distance
      amove deltapi     atime             ;move sound source past
            delayw      asource                 ;  the listener
            out   amove * ampfac


                        February 20, 1991





                             - 51 -


      ar    comb  asig, krvt, ilpt[, istor]
      ar    alpass      asig, krvt, ilpt[, istor]
      ar    reverb      asig, krvt[, istor]

An input signal is reverberated for krvt seconds  with  "colored"
(comb),  flat  (alpass),  or  "natural  room"  (reverb) frequency
response.


INITIALIZATION

ilpt - loop time in seconds, which determines the "echo  density"
of  the reverberation.  This in turn characterizes the "color" of
the comb filter whose frequency response curve will contain  ilpt
*  sr/2  peaks spaced evenly between 0 and sr/2 (the Nyquist fre-
quency).  Loop time can be as large as available memory will per-
mit.   The  space required for an n second loop is 4n * sr bytes.
comb and alpass delay space  is  allocated  and  returned  as  in
delay.

istor (optional) - initial disposition of delay-loop  data  space
(cf.  reson).  The default value is 0.


PERFORMANCE

These filters reiterate input with an echo density determined  by
loop  time  ilpt.   The  attenuation  rate  is independent and is
determined by krvt, the reverberation time (defined as  the  time
in  seconds  for  a signal to decay to 1/1000, or 60 db down from
its original amplitude).  Output from a comb filter  will  appear
only  after  ilpt  seconds;  alpass  output  will begin to appear
immediately.

A reverb unit is composed of four comb filters in  parallel  fol-
lowed  by  two  alpass  units  in  series.  Looptimes are set for
optimal "natural room response." Core  storage  requirements  for
this  unit  are proportional only to the sampling rate, each unit
requiring approximately 3K words for every 10KC.  It  is  usually
expedient  to  mix several signals together before reverberation.
Since reverb output will begin to appear only after  1/20  second
or  so  of  delay,  and often with less than three-fourths of the
original power, it is common to output both the  source  and  the
reverberated signal together.



Example:

      a1    oscili      k1, a1, 1         ;create two signals
      a2    oscili      k2, a2, 2
      a3    reverb      a1+a2, 1.5  ;mix, then reverberate
            outs  a1+a3, a2+a3      ;send 1 source + both reverbs
                              ;through each speaker



                        February 20, 1991





                             - 52 -


OPERATIONS USING SPECTRAL DATA-TYPES

      dsig  octdown     asig, iocts, isamps[, idisprd]
      wsig  noctdft           dsig, iprd, ifrqs, iq[, ihann, idbout, idsines]
      wsig  specscal    wsigin, ifscale, ifthresh
      wsig  specaddm    wsig1, wsig2[, imul2]
      wsig  specdiff    wsigin
      wsig  specfilt    wsigin, ifhtim
            specdisp    wsig, iprd[, iwtflg]
      ksum  specsum     wsig[, interp]

These units generate and process non-standard audio  data  types,
such   as   down-sampled  time-domain  audio  signals  and  their
frequency-domain (spectral) representations.  The new data  types
(d-,  w-) are self-defining, and the contents are not processable
by any other Csound units.  The unit generators are experimental,
and subject to change between releases;  they will also be joined
by others later.  Their inclusion here is to offer the user  some
initial experience in spectral data processing.


INITIALIZATION

idisprd (optional)  -  if  non-zero,  display  the  output  every
idisprd seconds.  The default value is 0 (no display).

ihann, idbout, idsines (optional) -  if  non-zero,  then  respec-
tively:  apply a hanning window to the input;  convert the output
magnitudes to dB; display the  windowed  sinusoids  used  in  DFT
filtering.   The  default values are 0, 0, 0 (rectangular window,
magnitude output, no sinusoid display).

imul2 (optional) - if non-zero, scale the wsig2 magnitudes before
adding.  The default value is 0.

iwtflg (optional) - wait flag.  If non-zero,  hold  each  display
until released by the user.  The default value is 0 (no wait).

interp (optional) - if non-zero, interpolate  the  output  signal
ksum.   The  default  value is 0 (repeat the signal value between
changes).

PERFORMANCE

octdown - put signal asig through iocts  successive  applications
of  octave  decimation  and  downsampling,  and   preserve isamps
down-sampled values in each octave.   Optionally display the com-
posite buffer every idisprd seconds.

noctdft - generate a constant-Q, exponentially-spaced DFT  across
all  octaves  of the multiply-downsampled input dsig.  Every iprd
seconds, each octave of dsig is optionally windowed  (ihann  non-
zero),   filtered  (using  ifrqs  parallel  filters  per  octave,
exponentially spaced, and with frequency/bandwidth Q of iq),  and
the  output  magnitudes  optionally  converted to dB (idbout non-


                        February 20, 1991





                             - 53 -


zero).  This unit produces  a  self-defining  spectral  datablock
wsig,  whose  characteristics  are  readable  by  any  units that
receive it as input, and for which it becomes  the  template  for
output.

specscal -  scale  an  input  spectral  datablock  with  spectral
envelopes.   Function  tables  ifthresh and ifscale are initially
sampled across the (logarithmic) frequency  space  of  the  input
spectrum;  then each time a new input spectrum is sensed the sam-
pled values are used to scale each of its magnitude  channels  as
follows:  if  ifthresh  is non-zero, each magnitude is reduced by
its corresponding table-value (to not less than zero);  then each
magnitude is rescaled by the corresponding ifscale value, and the
resulting spectrum written to wsig.

specaddm - do a weighted add of  two  input  spectra.   For  each
channel of the two input spectra, the two magnitudes are combined
and written to the output according to:  magout = mag1in + mag2in
*  imul2.  The operation is performed whenever the input wsig1 is
sensed to be new.  This unit will (at Initialization) verify  the
consistency  of  the two spectra (equal size, equal period, equal
mag types).

specdiff - find the positive difference values  between  consecu-
tive  spectral  frames.  At each new frame of wsigin, each magni-
tude value is compared with its  predecessor,  and  the  positive
changes  written  to the output spectrum.  This unit is useful as
an energy onset detector.

specfilt - filter each channel of an input spectrum.  At each new
frame  of  wsigin,  each  magnitude value is injected into a 1st-
order lowpass recursive filter, whose half-time constant has been
initially  set  by  sampling  the ftable ifhtim across the (loga-
rithmic) frequency space of the input spectrum.  This unit effec-
tively applies a persistence factor to the data occurring in each
spectral  channel,  and  is  useful  for  simulating  the  energy
integration that occurs during auditory perception.

specdisp - display the magnitude values of  spectrum  wsig  every
iprd seconds (rounded to some integral number of wsig's originat-
ing iprd).

specsum - sum the magnitudes across all channels of the spectrum.
At each new frame of wsig, the magnitudes are summed and released
as a scalar ksum signal.  Between frames, the  output  is  either
repeated  or interpolated at the K-rate.  This unit produces a k-
signal summation of the magnitudes present in the spectral  data,
and  is thereby a running measure of its moment-to-moment overall
strength.



Example:

      asig  in                      ;get external audio


                        February 20, 1991





                             - 54 -


      dsamp octdown     asig, 6, 180, 0         ;downsample in 6 octaves
      wsig1 noctdft     dsamp,.02,12,33,0,1,1   ; & calc 72-point dft (db)
      wsig2 specdiff    wsig1             ;sense onsets
      wsig3 specfilt    wsig2, 2                ; & absorb slowly
            specdisp    wsig1, .1               ;display all spectra
            specdisp    wsig2, .1
            specdisp    wsig3, .1
      kstren      specsum     wsig3, 1                ;sum final mags, and ksmooth

















































                        February 20, 1991





                             - 55 -


SENSING & CONTROL

      ktemp tempest     kin, iprd, imindur, imemdur, ihp, ithresh, ihtim, ixfdbak,
                              istartempo, ifn[, idisprd, itweek]

Estimate the tempo of beat patterns in a control signal.

INITIALIZATION

iprd - period between analyses (in seconds).  Typically about .02
seconds.

imindur - minimum duration (in seconds) to serve  as  a  unit  of
tempo.  Typically about .2 seconds.

imemdur - duration (in seconds)  of  the  kin  short-term  memory
buffer  which  will  be scanned for periodic patterns.  Typically
about 3 seconds.

ihp - half-power point (in cps) of  a  low-pass  filter  used  to
smooth  input  kin  prior to other processing.  This will tend to
suppress activity that moves much faster.  Typically 2 cps.

ithresh - loudness threshold  by  which  the  low-passed  kin  is
center-clipped  before  being  placed in the short-term buffer as
tempo-relevant data.  Typically at the noise floor of the  incom-
ing data.

ihtim - half-time (in seconds)  of  an  internal  forward-masking
filter  that masks new kin data in the presence of recent, louder
data.  Typically about .005 seconds.

ixfdbak - proportion of this unit's anticipated value to be mixed
with  the  incoming kin prior to all processing.  Typically about
.3.

istartempo - initial tempo (in beats per minute).  Typically 60.

ifn - table number of a stored function (drawn left-to-right)  by
which the short-term memory data is attenuated over time.

idisprd (optional) - if non-zero, display the short-term past and
future  buffers  every  idisprd  seconds  (normally a multiple of
iprd).  The default value is 0 (no display).

itweek (optional) - fine-tune adjust this  unit  so  that  it  is
stable  when  analyzing events controlled by its own output.  The
default value is 1 (no change).

PERFORMANCE

tempest examines kin for amplitude periodicity, and  estimates  a
current  tempo.   The  input  is  first  low-pass  filtered, then
center-clipped, and the residue placed  in  a  short-term  memory
buffer   (attenuated   over   time)  where  it  is  analyzed  for


                        February 20, 1991





                             - 56 -


periodicity  using  a  form  of  autocorrelation.   The   period,
expressed  as  a  tempo  in beats per minute, is output as ktemp.
The period is also used  internally  to  make  predictions  about
future amplitude patterns, and these are placed in a buffer adja-
cent to that of the input.   The  two  adjacent  buffers  can  be
periodically displayed, and the predicted values optionally mixed
with the incoming signal to simulate expectation.

This unit is useful for sensing the metric  implications  of  any
k-signal (e.g.  the RMS of an audio signal, or the second deriva-
tive of a conducting gesture), before sending to a  tempo  state-
ment.

Example:
      ksum  specsum     wsignal, 1              ; sum the amps of a spectrum
      ktemp tempest     ksum, .02, .1, 3, 2, 800, .005, 0, 60, 4, .1, .995;   & look for beats









































                        February 20, 1991





                             - 57 -


      kx, ky      xyin        iprd, ixmin, ixmax, iymin, iymax[, ixinit, iyinit]
            tempo       ktempo, istartempo

Sense the cursor position in an input window.  Apply  tempo  con-
trol to an uninterpreted score.


INITIALIZATION

iprd - period of  cursor  sensing  (in  seconds).   Typically  .1
seconds.

xmin, xmax, ymin, ymax - edge values for the x-y coordinates of a
cursor in the input window.

ixinit, iyinit (optional) - initial x-y coordinates reported; the
default values are 0,0.  If these values are not within the given
min-max range, they will be coerced into that range.

istartempo - initial tempo (in beats per minute).  Typically 60.


PERFORMANCE

xyin samples the cursor x-y position in  an  input  window  every
iprd  seconds.   Output values are repeated (not interpolated) at
the K-rate, and remain fixed until a new change is registered  in
the window.  There may be any number of input windows.  This unit
is useful for Realtime control, but continuous motion  should  be
avoided if iprd is unusually small.

tempo allows the performance speed of Csound scored events to  be
controlled  from within an orchestra.  If the csound command's -B
(beatmode) flag is set, scored  events  will  be  performed  from
their  uninterpreted  p2  and  p3 (beat) parameters, at a default
tempo of  60  beats  per  minute.   When  a  tempo  statement  is
activated  in  any  instrument  (with ktempo > 0.), the operating
tempo will be set to ktempo beats per minute.  There may  be  any
number  of  tempo  statements  in  an  orchestra,  but coincident
activation is best avoided.


Example:

      kx,ky xyin   .05, 30, 0, 120, 0, 75       ; sample the cursor
            tempo  kx, 75                 ; and control the tempo of performance











                        February 20, 1991





                             - 58 -


SOUND INPUT & OUTPUT

a1          in
a1, a2            ins
a1, a2, a3, a4    inq
a1          soundin     ifilno[, iskptim][, iformat]
a1, a2            soundin     ifilno[, iskptim][, iformat]
a1, a2, a3, a4    soundin     ifilno[, iskptim][, iformat]
            out         asig
            outs1       asig
            outs2       asig
            outs        asig1, asig2
            outq1       asig
            outq2       asig
            outq3       asig
            outq4       asig
            outq        asig1, asig2, asig3, asig4

These units read/write audio data to/from an external  device  or
stream.

INITIALIZATION

ifilno - integer suffix (n) of a binary file  named  'soundin.n',
assumed to be in the directory SFDIR (see also GEN01).

iskptim (optional) -  time  in  seconds  of  input  sound  to  be
skipped.  The default value is 0.

iformat (optional) - specifies the audio data file  format  (1  =
8-bit  signed char, 2 = 8-bit A-law bytes, 3 = 8-bit U-law bytes,
4 = 16-bit short integers, 5 = 32-bit long integers, 6  =  32-bit
floats).   If  iformat = 0 it is taken from the soundfile header,
and if no header from the csound -o command  flag.   The  default
value is 0.

PERFORMANCE

in, ins, inq - copy the current values from  the  standard  audio
input  buffer.  If the command flag -i is set, sound is read con-
tinuously from the audio input stream (e.g. stdin or a soundfile)
into  an  internal  buffer.    Any number of these units can read
freely from this buffer.

soundin is functionally an audio generator that derives its  sig-
nal  from a pre-existing file.  The number of channels read in is
set by the number of result cells, a1, a2, etc.  A  soundin  unit
opens this file whenever the host instrument is initialized, then
closes it again each time the instrument is  turned  off.   There
can  be any number of soundin units within a single instrument or
orchestra; also, two or more of them can read simultaneously from
the same external file.

out, outs, outq send audio  samples  to  an  accumulating  output
buffer  (created at the beginning of performance) which serves to


                        February 20, 1991





                             - 59 -


collect the output of all active instruments before the sound  is
written  to  disk.  There can be any number of these output units
in an instrument.  The type (mono, stereo, or  quad)  must  agree
with  nchnls, but units can be chosen to direct sound to any par-
ticular channel:  outs1 sends to stereo channel 1, outq3 to  quad
channel 3, etc.



















































                        February 20, 1991





                             - 60 -


a1, a2, a3, a4    pan         asig, kx, ky, ifn[, imode][, ioffset]

Distribute an audio signal amongst four channels  with  localiza-
tion control.


INITIALIZATION

ifn - function table number of a stored  pattern  describing  the
amplitude  growth  in a speaker channel as sound moves towards it
from an adjacent speaker.  Requires extended guard-point.

imode (optional) - mode of the kx, ky position values.  0  signi-
fies raw index mode, 1 means the inputs are normalized (0-1). The
default value is 0.

ioffset (optional) - offset indicator for kx, ky.  0  infers  the
origin  to  be at channel 3 (left rear); 1 requests an axis shift
to the quadraphonic center.  The default value is 0.


PERFORMANCE

pan takes an input signal asig and distributes  it  amongst  four
outputs  (essentially quad speakers) according to the controls kx
and ky.  For normalized input (mode=1) and no  offset,  the  four
output  locations are in order:  left-front at (0,1), right-front
at (1,1), left-rear at the origin (0,0), and right-rear at (1,0).
In the notation (kx, ky), the coordinates kx and ky, each ranging
0-1, thus control the 'rightness' and 'forwardness'  of  a  sound
location.

Movement between speakers is by amplitude  variation,  controlled
by  the  stored  function table ifn.  As kx goes from 0 to 1, the
strength of the right-hand signals will grow from  the  left-most
table  value  to the right-most, while that of the left-hand sig-
nals will progress from the right-most table value to  the  left-
most.   For  a  simple  linear  pan,  the table might contain the
linear function 0-1.  A more correct pan that maintains  constant
power  would  be  obtained  by  storing  the  first quadrant of a
sinusoid.  Since pan will scale and truncate kx and ky in  simple
table lookup, a medium-large table (say 8193) should be used.

kx, ky values are not restricted to 0-1.  A circular motion pass-
ing through all four speakers (escribed) would have a diameter of
root 2, and might be defined by a circle of radius R =  root  1/2
with center at (.5,.5).  kx, ky would then come from Rcos(angle),
Rsin(angle),  with  an   implicit   origin   at   (.5,.5)   (i.e.
ioffset=1).   Unscaled  raw values operate similarly.  Sounds can
thus be located anywhere in the polar or cartesian plane;  points
lying outside the speaker square are projected correctly onto the
square's perimeter as for a listener at the center.

Example:
            instr 1


                        February 20, 1991





                             - 61 -


      k1    phasor      1/p3              ;fraction of circle
      k2    tablei      k1, 1, 1                ;sin of angle (sinusoid in f1)
      k3    tablei      k1, 1, 1, .25, 1        ;cos of angle (sin offset 1/4 circle)
      a1    oscili      10000, 440, 1           ;audio signal ..
   a1,a2,a3,a4    pan   a1, k2/2, k3/2, 2, 1, 1 ;  sent in a circle (f2=1st quad sin)
            outq  a1, a2, a3, a4
            endin


















































                        February 20, 1991





                             - 62 -


SIGNAL DISPLAY

            print       iarg[, iarg, ...]
            display           xsig, iprd[, iwtflg]
            dispfft           asig, iprd, iwsiz[, iwtyp][, idbout][, iwtflg]


These units will print orchestra Init-values, or produce  graphic
display  of  orchestra  control signals and audio signals.   Uses
X11 windows if enabled, else (or if -g flag is set) displays  are
approximated in ascii characters.


INITIALIZATION

iprd - the period of display in seconds.

iwsiz - size of the input window in samples. A  window  of  iwsiz
points will produce a Fourier transform of iwsiz/2 points, spread
linearly in frequency from 0 to sr/2.  iwsiz must be a  power  of
2.  The windows are permitted to overlap.

iwtyp (optional) - window type.  0 = rectangular,  1  =  hanning.
The default value is 0 (rectangular).

idbout (optional) - units of output for the Fourier coefficients.
0 = magnitude, 1 = decibels.  The default is 0 (magnitude).

iwtflg (optional) - wait flag.  If non-zero, each display is held
until released by the user.  The default value is 0 (no wait).


PERFORMANCE

print - print the current  value  of  the  I-time  arguments  (or
expressions) iarg at every I-pass through the instrument.

display - display the audio or control  signal  xsig  every  iprd
seconds, as an amplitude vs time graph.

dispfft - display the Fourier Transform of the audio signal  asig
every iprd seconds using the Fast Fourier Transform method.




Example:

      k1    envlpx        1,.03,p3,.05,1,.5,.01 ;generate a note envelope
            display       k1, p3                ;and display entire shape







                        February 20, 1991


