PCMUSIC VERSION 0.9
(c) Copyright 1995 by F. Richard Moore University of California, San Diego All Rights Reserved
NOTE: THIS PROGRAM IS IN PRELIMINARY FORM AND IS BEING SUPPLIED FOR TEST PURPOSES ONLY. IT HAS NOT BEEN THOROUGHLY TESTED AND MAY WELL HAVE BUGS. USE IT AT YOUR OWN RISK!
Download PCMUSIC v0.9: pcm09.exe
pcmusic takes a text (ASCII) file written in the pcmusic input language and creates a soundfile (in .wav format) that corresponds to it. For this reason, pcmusic is a member of the class of programs sometimes known as "acoustic compilers". pcmusic is a version of the cmusic sound synthesis program for the IBM PC and compatibles. This readme file explains only the differences between cmusic and pcmusic. A full explanation of cmusic can be found in the book Elements of Computer Music, by F. Richard Moore (Prentice-Hall, 1990).
SYSTEM REQUIREMENTS:
pcmusic runs under DOS on any PC-compatible computer with a 386+387 or better CPU. You also need a properly installed sound card capable of handling .wav-format files (pcmusic is compatible with either 8- or 16-bit, mono or stereo .wav files). Most users will probably find it convenient to run pcmusic in a DOS window under Windows. Be advised that soundfiles can become quite large, so even though pcmusic itself doesn't require much space, a 1-minute stereo 16-bit soundfile at a sampling rate of 44,100 samples per second requires about 10.6 megabytes of disk space. pcmusic is also dynamic in that it grows and shrinks according to its tasks. Some large score files may run up against the 640K DOS memory limit. Future versions of this software will not have such limitations, of course. The future never has limits. Only the present.
INSTALLATION
pcm09.exe is a "self-extracting" compressed archive which contains all necessary pcmusic files. Create an empty directory called \pcm (or any other name of your choice) and place this readme file and the compressed pcm09.exe file there. Execute the pcm09 command in the pcm directory - this will expand the compressed file into the many pcmusic files. If you use any home directory for pcmusic besides pcm, edit the -I and -H parameters specified in pcm.bat file to reflect your choice. You will also probably want to add the pcm directory to your DOS path in the autoexec.bat file.
COMMAND
cmusic was originally developed to run under UNIX, so pcmusic cannot be exactly the same (it is, in fact, completely rewritten). For example, to compile the score file "score.sc" into the soundfile "pcm.wav", use the command
pcm score
This runs the pcm.bat command file which executes several preprocessors as well as the pcmusic program itself. Note that the ".sc" extension is not mentioned in the command, but is required by the pcm.bat file. The output of the first preprocessor (which corresponds to the C macro preprocessor) is named "score.i". The output of the second preprocessor is called "score.pp2", etc. The output of the final preprocessor is read by the pcmusic program itself, which in turn creates the soundfile "pcm.wav" (by default - the user is free to modify the pcm.bat file as desired, though the original conventions are recommended). Once the soundfile is produced, it can be renamed manually (using, say the DOS "ren" command), or the pcm.bat file can be changed to rename it automatically as desired (to, say, "score.wav").
DIFFERENCES BETWEEN PCMUSIC AND CMUSIC
No "set" Command
Unlike cmusic, pcmusic has no "set" command. In DOS/Windows style, pcmusic uses a file called "pcmusic.ini" to set parameters such as sampling rate, number of channels, etc. BE SURE TO MAKE ONLY SIMPLE CHANGES TO THIS FILE. For example, deleting lines or introducing extraneous spaces can corrupt the pcmusic.ini file (i.e., it won't work). For this reason, a "spare", read-only copy of the original pcmusic.ini file called "pcmusic.org" is included. pcmusic can handle any sampling rate, but your sound card will probably restrict your choices to, say, 44100, 22050, and perhaps 11025. Only stereo, mono, and 8- or 16-bit samples are presently supported. You can set the listing file to "stderr" or "stdout", or to a filename, according to your preference. You can change such things as speaker coordinates and i/o block length, but you should probably leave such values alone unless you really know what you're doing.
The pcmusic.ini file is assumed to be in the current directory unless the -Hdir flag is given to the pcmusic command, which sets the pcmusic home directory (where it looks for pcmusic.ini) to dir.
The Macro Preprocessor
pcmusic has its own C-like macro preprocessor which supports three kinds of comments (either old C-style /* and */, or new C-style //, or cmusic-style curly braces {}). Also, only #include and #define statements work (other features of the real C preprocessor, such as #ifdef, are not included), and the #include statement works either for double-quote-enclosed filenames (which may include complete path names, of course, otherwise only the current directory is searched) or angle bracketed (<>) filenames, which are searched for in the include directory. The macro preprocessor command accepts a -Idir flag which sets the include directory to dir.
The "cmusic.h" File
The "cmusic.h" file is included and is the same as it is under cmusic. The file may be in the current directory or in the include directory unless a complete path name is given.
The Unit Generators v A copy of the file "ugtable.h" is included which contains all the unit generator names and calling conventions in the current version of pcmusic. Basically, they're all here, including space, fltdelay, and a sndfile unit generator that automatically adapts itself to 8- or 16-bit sample data formats. Instead of the cmusic notation [bpvn] (meaning i/O Block, note Parameter, global Variable, or constant (Number)), pcmusic simply uses [be], meaning i/o Block or Expression. Expressions may be any constant expression (that is, they may not contain signals such as b1 or b2). pcmusic does allow unit generator statements to contain expressions containing note parameters (unlike cmusic). For example, it is quite legal in pcmusic to specify the frequency input to an oscillator as 2*p5, which is a constant expression [e].
The Gen Programs
The gen0, gen4, gen5, and gen6 programs have been built into pcmusic for efficiency. All other gen programs are external, as with cmusic, and may be user-supplied, as with cmusic. gen3, chubby and shepenv are supplied, but others are missing. Since DOS doesn't have real pipes like UNIX, pcmusic communicates with the gen programs through a temporary data file called "_pcgen.out", so try not to use that name for anything else.
Utility Programs
A utility program called "waveinfo" is included for examining .wav file header information. "wave8" and "wave16" are simple sinewave-generators for generating 8- and 16-bit .wav files for test purposes. Typing these program names without parameters will produce a help statement that should be self-explanatory. If it isn't, you probably didn't want to be using these programs in any case.
Help
There isn't any. There are a few example score files are included here and many cmusic examples in the book mentioned above. Most of the latter should work with little or no change under pcmusic (only such things as set commands (which are benign - if pcmusic encounters one it simply gets ignored) and #include statement conventions). I'm willing to answer brief questions or help solve real program problems via email, but I can't explain the basic use of pcmusic - for that you are referred to the book. Good luck!
-F Richard Moore
Professor of Music
University of California, San Diego
frm@ucsd.edu