GEN(1carl)          Unix Programmer's Manual           GEN(1carl)
 

     NAME
          gen0 gen1 gen2 gen3 gen4 gen5 gen6 - cmusic function
          generators

     SYNOPSIS
          genN -LN [ flags ] specification > floatsams
          where -LN specifies N floatsams of output.

     DESCRIPTION
          These programs are the set of gen commands published with
          cmusic(1carl). They are utilized in cmusic to generate
          waveform, envelope, and other control functions.  They are
          actually standalone programs which can be run ``as is'' to
          create arbitrary functions for other purposes.  In addition
          to cmusic, for instance, Player(1carl) provides an interface
          to utilize these programs.  There are other gen type
          commands that can be used in the context of a cmusic score.
          Refer to the SEE ALSO section below.

          This manual page shows their use as standalone programs.
          Refer to cmusic(1carl) for their use in that context.

          All programs except gen0 require a -LN flag which specifies
          the length of the function to create.

          In addition, some of these programs take other optional
          flags.  Two flags in particular, -o and -c determine whether
          the function created is ``open'' or ``closed''.  An open
          funciton is usually required for periodic functions designed
          for iterative use, as in oscillators which read a function
          many times in succession.  In this case, the last point of
          the function does not go full cycle, but stops one sample
          short, so that when the oscillator wraps around to the
          beginning again, it experiences no discontinuity, and
          therefor produces no click.

          A closed function is used e.g. for amplitude control.  Here
          one typically wants the last value equal to the first.  If,
          for instance, a trapezoid envelope function were generated
          in open form, the last point would not be quite zero, and
          there would likely be a click at the end of a note.

          The programs that allow open/closed function control specify
          this with -o and -c flags.
 

     GEN0 - Normalize a function

               gen0 [ -LN ] [ max ] < floatsams > floatsams

          Gen0 scales the function it reads on its standard input so
          that the maximum value of the function is equal to max. If
          max is omitted, it is assumed to be 1.0. gen0 will insure
          that no value exceeds the absolute value of max in either
          case.  For this gen statement only, the length flag may be
          ommitted, in which case gen0 reads its standard input until
          it is exhausted.  If the length flag is supplied, gen0 stops
          reading input after that many samples are read.

          Note that cmusic implements gen0 internally.  This
          standalone program simulates its behavior. Because of the
          nature of the algorithm, gen0 must read up the entire
          function before writing it out.  Because of this, care
          should be made not to use it to normalize extremely large
          data streams.

     GEN1 - straight line segment function generator

               gen1 -LN t1 v1   t2 v2   . . .   tN vN > floatsams

          gen1 generates a (closed) function which starts with value
          v1 at point t1 (the beginning of the function), continues in
          a straight line to value v2 at point t2, etc., until final
          value vN is reached at the end of the function.  Example:
               gen1 -L1024  0 0  1/3 1  2/3 1  1 0 > file
          This generates a trapezoidal function; straight line from 0
          to 1 for the first third of the function, level value of 1
          for the middle third, falling from 1 to 0 in the final
          third.

     GEN2 - Fourier synthesis function generator

               gen2 -LN [ -o (default) or -c] a1 a2 ... aN    b0 b1
               ... bM     N  > floatsams

          aK is the amplitude of harmonic K in sine phase, (the
          fundamental frequency, corresponding to a full period of the
          function, corresponds to K = 1), and bK is the amplitude of
          harmonic K in cosine phase.  Note that the first cosine
          component is at 0 Hz ("D.C."). The shape of the final (open)
          function is determined by the sum of all the components
          specified; the peak amplitude of the final function is
          normalized to 1.0.  The use of gen2 is deprecated.  Use gen5
          whenever you wish to understand what you are doing.
          Examples:
               (sine wave)
                    gen2 -L32 1   1
               (cosine wave)
                    gen2 -L32 0 1   0
               (the first five components of a square wave)
                    gen2 -L4096 1 0 1/3 0 1/5   5
               (same as in the previous example with a .5 D.C. offset)
                    gen 0 gen2 f4 1 0 1/3 0 1/5 .5 5

     GEN3 - simple line segment function generator

               gen3 -LN v1 v2 ... vN  > floatsams

          The arbitrarily long list of values v1, ..., vN specifies
          relative amplitudes at equally spaced points along a
          (closed) function. Thus
               gen3 -L32    0 1 1 0
          specifies a trapezoidal function which has 3 parts: the
          first rises in a straight line from 0 to 1, the second is
          steady at 1, and the third falls from 1 to 0.  If all values
          are positive, the function is scaled to be only positive.
          All negative values result in an all negative function.
          Values may be both positive and negative, resulting in a
          function which ranges between +1 and -1.

     GEN4 - exponential curve segment generator

               gen4 -LN t1 v1 x1   t2 v2 x2   . . .   tN vN >
               floatsams

          The t values specify positions along the horizontal axis on
          an arbitrary scale (as in gen1), the v values specify values
          of the (closed) function at these points, and the x values
          specify transitions from one point to another.  x = 0 will
          yield a straight line, x < 0 will yield an exponential
          transition, and x > 0 will yield a logarithmic transition.
          If segment[J,i] is the i-th function value in the transition
          from v[J] to v[J+1], then its shape is determined by the
          formula:
               segment[J,i] = v[J] + (v[J+1] - v[J])*(1 -
               exp(i*x[J]/(N-1)))/(1 - exp(x[J]))

          for 0 <= i < N, where N is the number of function points
          between t[J] and the next horizontal value. No x value is
          given after the final point.  Examples:
               (straight line transitions)
                    gen4 -L32  0 0 0  1/3 1 0  2/3 1 0  1 0
               (exponential transitions)
                    gen4 -L32  0 0 -1  1/3 1 0  2/3 1 -1  1 0
               (similar to last example but with quicker exponential
               transitions)
                    gen4 -L32  0 0 -5  1/3 1 0  2/3 1 -5  1 0
          The x value specifies the number of exponential time
          constants between the endpoints of a transition.  A small
          negative value specifies a curve not very different from a
          straight line, but which gets near the second value more
          quickly.  A large negative value is more curved, and
          approaches the second value more quickly.  The latter kind
          of shape is very useful for specifying very sharp attacks
          while avoiding clicks, for example.

     GEN5 - Fourier synthesis generator

               gen5 -LN h1 a1 p1  h2 a2 p2  . . .  hN aN pN >
               floatsams

          Each Fourier component of the (open) function is described
          by a triplet specifying a harmonic number, an amplitude, and
          a phase offset relative to sine phase.  As many components
          may be supplied as desired, but all three values must be
          supplied for each component. Phase angles are in radians
          (cf. "Deg" post operator in expressions); harmonic numbers
          need not be integers.  Examples:
               (a sine wave)
                   gen5 -L32 1 1 0
               (first 3 components square wave)
                   gen5 -L32 1 1 0 3 1/3 0 5 1/5 0
               (raised cosine wave)
                   gen5 -L32 1 -.5 90Deg 0 .5 90Deg

     GEN6 - random table generator

               gen6 -LN  > floatsams
 
 

          Gen6 fills the function named with random samples in the
          range -1 to +1.

     AUTHOR
          F. R. Moore

     SEE ALSO
          genraw(1carl), step(1carl), cspline(1carl), chubby(1carl),
          quad(1carl).

     BUGS
          There are some differences between running gen programs
          within cmusic and running them standalone.  Unlike cmusic,
          commas should not appear to separate arguments on the
          command line.  The postoperators that relate to sampling
          rate are not available, such as Hz and sec.