VMUSIC -- User's Guide


INTRODUCTION:

VMUSIC is a program designed to do what other music programs 
can't do: play actual 3-part music on any PC. As you know, the 
IBM PC was designed to handle only one tone at a time. VMUSIC 
breaks that barrier.


INSTALLATION:

Install VMUSIC by copying all of the files included with the 
program on a floppy disk or into a directory on your hard disk.  
If you're using a floppy disk system, you may want to make your 
VMUSIC disk into a self-booting disk. To do this, format a 
blank disk with the /S switch. Once this is done, copy the 
VMUSIC files onto the new disk.


RUNNING VMUSIC:

Start VMUSIC with the command: VMUSIC filename. Several sample 
song files are included.  To play the song "Greensleeves," for 
example, give the command this way:

VMUSIC GREEN <Enter>

Next, you'll be prompted for two numbers. The first controls the 
speed at which the song is played. The second controls the 
overall pitch of the notes played by VMUSIC. You'll see 
suggestions for numbers for PCs with various clock speeds. You'll 
have to experiment to find the ideal values for your own PC.

Once you determine those values, they should apply to all the 
songs you want to play.

VMUSIC can also be started with three command-line arguments:

        1.      Song file name
        2.      Tempo value
        3.      Value to set relative pitch

A typical command line for a 12 MHZ AT might be:

VMUSIC GREEN -8 6

Negative numbers may be used for tempo on really fast ATs or 386 
machines.

VMUSIC was first written for PCs and the first ATs (6 MHZ), but 
the world has since moved to 10-12 MHZ ATs and is moving to 
386 machines. This version will sound right on all of them.

Here are some values for tempo and pitch parameters to try with 
your PC:

           PC TYPE             Tempo         Pitch

           4.77 MHZ PC          10            1
           8 MHZ XT              0            2
           6 MHZ AT             -2            3
           12 MHZ AT            -8            6  

VMUSIC should be able to play music for about 25 continuous
minutes, ample for most purposes. It will output a total count 
of notes to the screen for a given song and this count may go as 
high as 30,000. For reference, BABYLON has about 400 notes.


CUSTOM BATCH FILES:

Once you determine the best numbers for VMUSIC tempo and pitch 
parameters, you can automate the process with a simple batch file.
Use a text editor like SLED to create the batch file. You can 
also use your word processor, but save the file as a pure ASCII 
file. Consult your word processor's manual for instructions.

For example, using the sample command for an 8 MHZ XT, as shown 
above, here is a batch file, called VM.BAT.

ECHO OFF          REM Turns off command display on screen.
CLS               REM Clears the screen.
VMUSIC %1 0 2     REM Starts VMUSIC with the song named as %1.

Now, to start VMUSIC, just give the command VM, followed by the 
name of the song file. The command might look like this:

VM GREEN

The batch file supplies the necessary speed and pitch parameters. 
Naturally, you'll replace the values shown in the sample file with 
the ones that work best on your own PC.

WRITING YOUR OWN SONG FILES:

You can create your own song files for VMUSIC, using a text 
editor, like SLED, or any other editor that can save files as 
pure ASCII files. Enter the music by typing in the commands, as 
described below. VMUSIC ignores carriage returns, so you can 
format the file any way you like.

Each voice is a separate part of the file. Write one complete set 
of instructions for each voice, then add the next voice.

VMUSIC uses the same syntax as BASICA/GWBASIC's PLAY statement for 
its song files. In addition, you add another command to tell 
VMUSIC which voice each line represents. All characters entered 
can be either upper or lower case.  

Here are the commands used in VMUSIC song files, presented in the 
order you are most likely to use. Note: Do not include the 
parentheses () when typing commands.

     V(n)
     This command tells VMUSIC which voice each line represents. 
Replace (n) with a number from 1 to 3. Voice 1 is usually the top 
line in sheet music, although you can use any order you wish.

     T(n)
     This command sets the tempo for your tune. Use a
number from 32-255 for (n). The tempo you select will remain in 
effect until it is changed.

     O(n)
     The "O" command sets the octave. Choose a value from
0-6 for (n). As with the "T" command, the octave setting remains in 
effect until changed. Middle C is in octave 3.

     M(L,N,S)
     The "M" command changes the way each note is played. An
"ML" command plays each note full length. To play each note for 7/8 
of its value, use the command "MN."  For staccato notes, each played 
for 3/4 of its value, the command is "MS."  These commands remain in 
effect until changed.

     A-G(n)
     These are the actual notes used in "Vmusic" tune
strings. They represent the normal notes of the scale. Specify the 
length for each note with a value for (n) between 1 and 64. Each 
number represents a type of note. For example, 1 represents a whole 
note, 4 is a quarter note, which gets one beat, and so on. Triplet 
figures are formed with note lengths that are multiples of 3.

     L(n)
     This command sets up a default length for all notes
that follow. Including the command "L8," for example, makes all 
the notes that follow equivalent to eighth notes unless another 
number is attached to an individual note.

     P(n)
    Use this command to create rests or pauses in your music.  
The values for (n) are the same as those used to specify note 
length. "P8" produces an eighth rest.

     < or >
     These commands are a shortcut for changing octaves. The
command "<" moves the following notes down one octave, while
">" moves them up one octave. As an example, here is a one- 
octave scale:  CDEFGAB>C. All VMUSIC octaves start with the 
note C.

     + or #
     Makes the preceding note sharp. Place this character 
after the note character, but before the length parameter.

     - (minus sign)
     Makes the preceding note flat.

     .(period character)
     Increases the length of the note or pause by a factor
of 1.5. Use this dot character in the same way you would in 
standard music notation. The command "C4." produces a dotted 
quarter note, equivalent to a quarter note plus an eighth note.

As a general rule, set the tempo (Tn), the mode (Mn), the voice 
(Vn), and the starting octave (On) at the beginning of each voice 
line. Enter other commands as you choose to create your tune.

One important caution is in order. For a VMUSIC song file to play 
properly, all voices must match perfectly in length. You must give 
the correct values for each note, or the voices will begin to lose 
synchronization. If your song file sounds odd, the problem is 
probably a mistake in writing one or more of the voices.

As an example, here's the actual text from the song file GREEN:

O4L8V1 d f4 g a. b16 a g4 e c. d16 e f4 d d c+ d e4 c+ <a4 >d f4 g 
a. b16 a g4 e c. d16 e f. e16 d c+ <b >c+ d4 d d4 p8 >c4. c. <b16 
a g4 e c. d16 e f4 d d. c+16 d e4 c+ <a4 p8 >c4. c. <b-16 a g4 e 
c. d16 e f. e16 d c+. <b16 >c+ d4. d4

O4L8V2 <d d4 e f. g16 f >c4 c c4 c d4 <a b-4 b- a4. a4 p8 >d4 c 
<f. g16 f >c4 c c4 c d4. <a4. f. g16 e d4 p8 a. g16 f f. g16 f >c4 
c c4 c d4 <a b-4 b- a4 a a4 p8 a. g16 f f. g16 f >c4 c c4 c d4. 
<a4. f. g16 e d4

By studying this two-voice song, comparing each line with the 
commands shown above, you can see how a song file is created. Like 
all musical instruments, creating music with VMUSIC takes practice.  
Experiment with song files, and you'll soon be writing complex music 
of your own.

For more information about the syntax of VMUSIC song files, 
consult the section on the PLAY statement in your BASICA or 
GWBASIC manual.

I would appreciate receiving copies of any music which you might 
code up for VMUSIC, and I would appreciate hearing from anyone 
able to get VMUSIC to run under any of the new multi-tasking OSs 
(particularly UNIX variants) on 386 equipment, while at least one 
other process is running.

VMUSIC is a public-domain program. I hope you enjoy using it to 
create music on your PC.

Ted Holden
HT Enterprises
5001 Seminary Rd. #621
Alexandria, Va. 22311
(703) 671-4562


TECHNICAL INFORMATION:

The music produced by VMUSIC is true multi-part harmony. Unlike 
PianoMan and other well known packages, nothing is being faked 
here. The technique used by VMUSIC is essentially that devised by 
Steve Muenter (RocketDyne).

Most programs that generate tones on the PC's speaker simply hook 
the speaker up to the timer chip, leaving the 80x86 chip free to 
do other things. Vmusic controls the speaker directly. There is a
port in the PC, one bit of which is a push-pull handle on the 
speaker;  if that bit is 0 and you move a 1 to it, or if it is a 1 
and you move a 0 to it, it moves the speaker back or forward 1 
count.

If you take a number, which you may regard as a frequency, and 
continuously add it into a 16-bit register, you will see 1's 
moving continuously to the left until the high-order bit in the 
register gets set (made 1). If you do this and then zero the 
register WHEN the high-order bit gets set, then you will observe 
that the process is cyclic and that the FREQUENCY with which the 
high-order bit gets set will be proportional to the number itself.
This means that if you multiply your original number by 3 and 
continue the process, then the frequency with which that 
high-order bit gets set will have increased three-fold, etc.

The idea is to feed that high-order bit to the port bit each time;  
you will get one push-pull each time the high-order bit gets set, 
which will be proportional to the number you used for a frequency.  
There are just enough registers in a PC to do this three times 
inside of some kind of a timing loop, length of notes times tempo.  
The proportionality of effect guarantees that, although the 
ABSOLUTE pitches may be ball-park at best, the RELATIVE pitches 
are perfect.