Previous Section: Cmix File Types
Structure of the CMIX scorefile
CMIX instrument instructions are interpreted through a command-parsing language called MINC (an acronym for Minc Is Not C). MINC, written by former Princeton student Lars Graf, is invoked automatically as a "front end" for every CMIX instrument. Each instrument has a set of subcommands or instructions understood by MINC. These subcommands are similar in appearance to C function calls.
Consider as an example the following scorefile for the CMIX instrument playinst (playinst is a simple wavetable-lookup oscillator instrument; the source code for it is distributed in the cmix/proto directory of the CMIX package):
output("funsound.snd")
makegen(1, 10, 1000, 1, 0.5, 0.3)
makegen(2, 7, 1000, 0, 1000, 1)
playinst(0, 7, 8.05, 10000, 0.3, 0.4)
The playinst instrument uses three subcommands here: output, makegen, and playinst. The function of the output subcommand is obvious -- it sets the name of the output soundfile. Note that names of files and other text strings are written in double quotes.
The two makegen subcommands set up the oscillator waveform and the rise/decay envelope for playinst. CMIX has a number of gen routines which are used by the makegen subcommand to build waveform wavetables, amplitude envelopes, other control envelopes, etc. The makegen parameters vary depending on which gen routine is being used, with the exception that the first three parameters always serve a fixed role. The first parameter (or p-field) is always the gen slot number, which is determined by the particular CMIX instrument being used. In the playinst example above, slot number one is designated in playinst as the waveform (makegen(1,...)), and slot number two is set as the rise/decay envelope (makegen(2,...)). the second p-field for the makegen subcommand is always interpreted as the gen routine number used to build the wavetable or envelope. gen routine 10 (makegen(1, 10,...)) specifies the relative strengths of waveform harmonics, beginning at p-field number four. The example
makegen(1, 10, 1000, 1, 0.5, 0.3)
will create a waveform with a first harmonic of amplitude 1, second harmonic with amplitude 0.5, and third harmonic with amplitude 0.3. gen routine 7 (makegen(2, 7,...)) will build an envelope of straight line segments:
makegen(2, 7, 1000, 0, 1000, 1)
will build a line from 0 to 1 over 1000 points in the envelope table, while:
makegen(2, 7, 1000, 0, 500, 1, 500, 0)
would specify an envelope that rises from 0 to 1 for 500 points of the table, and then falls from 1 to 0 for the next 500 points. The third p-field of the makegen subcommand sets the total number of points in the gen table. In CMIX, this can be set to any arbitrary number. 1000 is a good default for most applications. The use of p-fields 4 and greater depends upon the gen routine being used (again, the gen routine to be used is specified in p-field 2 of the makegen subcommand). The makegen.man1 file (in cmix/man) contains a description of most of the gen routines used in CMIX. The source code for all CMIX gen routines can be found (along with the source for the makegen subcommand itself) in the cmix/sys directory.
The playinst subcommand of the playinst instrument has a straightforward set of parameters:
playinst(start_time, duration, pitch, amplitude, rise_time, decay_time)
How can information (such as the playinst parameters) about CMIX instruments be found? Unfortunately, no comprehensive documentation exists for CMIX instruments. The best method is to consult the source code for a given instrument. By convention, CMIX instrument p-fields are listed as a comment towards the top of the source file. In the cmix/proto directory, the file playinst.c contains this information:
/* p0=start, p1=dur, p2=pitch, p3=amp, p4=riset, p5=decayt,
p6=percent in left channel (if stereo output file) */
/* assumes function 1 is waveform and function 2 is envelope function */
The instrument parameters are given, along with the information that gen slot 1 should contain the waveform and gen slot 2 should be the rise/decay envelope. Any number of additional playinst subcommands could be added to this playinst scorefile. Time-ordering doesn't matter (CMIX allows arbitrary time access for both input and output soundfiles), but the output and the two makegen subcommands must precede the first playinst subcommand. These output and makegen definitions will then be in effect for any subsequent playinst subcommands, but they may be overridden at any point in the CMIX scorefile by new output or makegen statements.
Running the CMIX playinst instrument with the example "playinst.sco" file above:
will probably result in the following report:
CMIX: cannot access file funsound.snd
headersize = 0
This is because the output soundfile must exist before an instrument can run. The following sequence of commands:
sfcreate -r 44100 -c 1 -i funsound.snd
playinst < playinst.sco
should produce the following output at the terminal:
( 9.25) 0.0000 .. 7.0000 MM c0=9.999000e+03
This report shows the starting and ending times of the generated output sound (0.0000 .. 7.0000), the approximate number of CPU seconds used to produce the output sound (9.25), and the peak amplitude for channel 0 in this segment of the soundfile (c0=9.999000e+03). If the output file had been stereo, CMIX would have reported separate peak amplitudes for channel 0 and channel 1.
Next Section: Using Cmix Built-in Subcommands
What is CMIX? - Index -
Cmix Home Page