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.