Category : Files from Magazines
Archive   : COMPUTE2.ZIP
Filename : VMUSIC.DOC

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

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+ d f4 g
a. b16 a g4 e c. d16 e f. e16 d c+ c+ d4 d d4 p8 >c4. c. a g4 e c. d16 e f4 d d. c+16 d e4 c+ c4. c. c. d16 e f. e16 d c+. c+ d4. d4

O4L8V2 c4 c c4 c d4 d4 c
c4 c c4 c d4. c4
c c4 c d4 c4 c c4 c 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.