File Archive

 
Output of file : ADMUSE3.DOC contained in archive : ADMUSE.ZIP

___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


AdMuse



AdMuse Version 3.0
by Bob Calbridge
December 26, 1989

Foreword
========

The executable and source code for AdMuse is copyrighted by the
author. The right to distribute this program is granted to all.
This does not grant anyone but the author the right to collect
any monies for the product other than a fair price for copying
costs. ("Fair", to the author, means the cost of a diskette, a
label, mailing cost, and a dollar worth of labor. It only takes
about 50 seconds to copy a diskette. At this rate, you could
earn over 60 dollars an hour by copying this program.) The
accompanying documentation is also considered to be part of the
package and is not to be modified, or deleted from, any
distributed form of the package, including compressed and/or
library (archived) type files. Permission is granted to end
users to modify it for their own use as long as the modified
form is not passed on to others. Under no circumstance is
permission granted to remove any mention of the author's name or
address where it might appear in either documentation or in the
executable code.

Please pass on the original files to friends, co-workers,
enemies and strangers who have AdLib cards.

This package is distributed under the Shareware concept. This
means that the author would really appreciate being compensated
for his efforts in producing this product. Response of this
nature urges the author to improve the product or to develop
other products of similar usefulness. A price of $10.00 is
asked, though greater amounts will not be refused. The money
will be used to restore the health I lost staying up 'til three
AM making this thing work. The test period for AdMuse is one
week. After this time you need to decide if AdMuse is worth the
asking price. If so, use the registraion form at the end of the
documentation to help me keep track of the who has this version.
You will be notified of updates to AdMuse. Local users will be
given the name of any local bulletin boards that contain the
update. Users outside the immediate Dallas area will be asked
to send a self-addressed diskette mailer along with a diskette.
Notification will include a list of all added features along
with an explanation of how they work, so you can decide if it is
.*..
worth the effort.

At any rate, I (the aforementioned author) welcome any comments
and suggestions any users of AdMuse might have concerning
improvements for this program. I am especially uneager, but
AdMuse______________________________________________ Page 1
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


willing, to hear about any bugs you may find in this code. I
will try to respond promptly to bugs in the program. If you
have any suggestions for improvements I ask that you make your
suggestion with some detail. By this I mean that if you have a
feature you would like to have added to the program, explain the
feature along with how you would like to see it coded. For
example, if you would like to see a feature that would let you
specify a smooth increase or decrease in volume of any single or
multiple voice selection, explain how you think it should be
expressed in the code (i.e. how to say you want a continuous
volume change, what voice(s) is(are) involved, the step rate,
the maximum volume, etc.) Some things may not be practical to
implement. The program, in its present form, doesn't like to
look ahead more than one character. Therefore, as in the
preceding example, if you wanted to try something like 1) begin
a volume increase beginning at the current volume, 2) increase
the volume to a maximum of .85 at the point you find an
_end_volume_increase_ marker, it would be difficult to look
ahead and calculate the step rate and the step spacing.

Now for the disclaimers. Great care has been put into this
program. However, it has been said that nothing is foolproof
(no aspersions intended). This program has been tested for all
foreseeable problems. How far I can see to the fore is up for
debate. All that I can say is that there are no intentionally
destructive code segments in this package. Having made the user
aware of these facts, I further state that I accept no
responsibility for any problems that may arise from the use of
this program, be it harm to hardware or software, unless it can
be proven that a deliberate effort was made on my part to cause
such.

The above mentioned comments, suggestions, criticism, et al. can
be sent to the me via my hard copy address:

Bob Calbridge
12904 Elam Road, Apt. 101
Balch Springs, TX 75180 <--- Dallas is a suburb

If sending to me at home, don't forget the apartment number.
The mailman has a habit of returning mail without it. Oh, and
you can send checks there too.

.*..
I've also been known to haunt the User-to-User bulletin board
system in the Dallas area. I regularly read the AdLib
conference.

I can generally be reached via e-mail at The Unix
Connection. My user id on this system is "bobc". The node name
is "attctc".

AdMuse
Copyright (C) 1990, Robert A. Calbridge, Jr.
AdMuse______________________________________________ Page 2
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Introduction
============

Some history
------------

This is version 3.0 of AdMuse. Versions 1.0 through 2.X are
obscure because they were distributed to just a few people.
They were also developed for different type systems. Version 1
was written for an S-100 system using a digital-to-analog
converter card manufactured by a company called NewTech.
Version 2 was written for a C-128 running CP/M and used the SID
chip for output. Version 2.0 was written in Z-80 assembler and
contained within its mere 12K of program space a screen editor,
a code compiler, a song player, an instrument selection menu,
and an instrument designer and banking program.

Version 3.0 is a large leap from the previous two. This is
mainly due to the capabilities of the AdLib card. Now seemed to
be the time to release it as there is now a large contingent of
PC owners out there that possess either AdLib cards or
compatible cards of another make.

For the record, AdMuse was developed using Turbo C 2.0, using
the large memory model.


What this is
------------

Back in the dark ages when a personal computer was something
that you had to put together by yourself, there was a company
that produced peripherals for the S-100 bus machines. One of
these peripherals was a very simple board that would take the
condition of the interrupt flip-flop and pass it on to an
external amplifier. The board came with a program that could
produce music in three voices through this board. The main
problem with the board was that the sound was quite raspy.
.*..
Despite this, it was quite an accomplishment for its time
considering the nature of the equipment.

Today's PC world has a number of good cards that produce better
sound and more voices. Chief among these is the AdLib card.
The AdLib card has an eleven voice capability in percussive mode
and nine in melodic mode. The AdLib is supported by an
impressive number of PC games that use it for sound effects and
music.

The primary storage format of stand-alone songs for the AdLib
card is usually contained in files with a .ROL extension. The
primary method of entering songs is by way of a program provided
by AdLib called The Visual Composer. The Visual Composer does a
good job of providing a means of entering songs. In a way, the
screen looks something like a roll of music for a player piano.
AdMuse______________________________________________ Page 3
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Using a mouse with The Visual Composer helps with the process.
However, there have been people for whom even this method of
transcribing doesn't work well. That is the reason for AdMuse.

AdMuse attempts to take the coding system employed on the old
S-100 bus system and use it to produce a ROL file. This first
release of the program may not address all the needs of someone
transcribing music. The program attempts to conform to the
original coding method with some extensions added for the
purpose of The Visual Composer. In a later revision there will
be some modifications to allow for chords, glissendoes,
arpegiation and accentuation (if I can find an appropriate way
of reducing it to text notation).
AdMuse______________________________________________ Page 4
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Where this program shines
-------------------------

(1) One of the major complaints that I've heard concerning The
Visual Composer is that it doesn't address the problem of
triplets. A triplet is a series of three notes that is played
in the space of two. The Visual Composer doesn't restrict this
type of notation but it does complicate it. It is necessary to
scan your music and determine in advance if a triplet is
required. You must then determine how many ticks per beat you
must define and this value must be a multiple of three. AdMuse
will do the necessary calculations and set the ticks per beat as
necessary.
.*..

(2) AdMuse uses a text code rather than a graphic method. There
are several advantages to this. First, if you are an
accomplished typist, you can keep the sheet music off to the
side and perform eye to hand transcribing with very little need
to watch the screen. Secondly, changes are easier to locate in
the code and modifications in the code are handled through your
own preferred ASCII editor. Thirdly, the ASCII nature of the
text makes it easy to use e-mail systems to pass code to others.
Finally, text code is easier to print out. It is more concise
than the graphics oriented output of the VCPRINT program and
prints faster.

(3) AdMuse provides for articulation. This means that you can
declare individual notes as staccato. There are three types of
articulation - short, long and extended. I intend that future
versions of the program will permit automatic articulation of
ranges of individual voices or the entire piece.

(4) AdMuse permits you to declare a key up front and allows you
to change it in the middle of a piece. The key declaration will
automatically provide sharps and flats for a given note if the
key demands it. You may individually make a note natural for
the duration of a measure to cancel a sharp or flat or you may
temporarily change a note to a sharp or flat for a measure.

(5) The coding method allows you to place markers at the
beginning of parts. The beginning of another part marks the end
of the preceding part. These markers permit the program to
repeat the part at other points in the program without having to
re-enter the code. Under the Visual Composer this requires
finding the beginning and end of a part and duplicating it
through a cut and paste process. This is tedious when trying to
keep track of your measure numbers.

(6) AdMuse provides the facility for the user to define his own
ASCII editor and an option for the user to call that editor from
within the program. This feature reduces the need to enter the
editor, exit the editor, enter AdMuse, compile the code, find an
error, exit AdMuse, enter the editor, .......
etc.
AdMuse______________________________________________ Page 5
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


(7) AdMuse provides a similar option for the user to define a
stand-alone player program for testing his code.



Possible problems with AdMuse
-----------------------------
.*..

(1) AdMuse is pretty free form in what it demands of the code.
The original coding method was a bit more free form than I made
this version. This version demands that modifiers immediately
follow the code segment it is meant to modify. Otherwise, you
are free to sprinkle white space where you please. In some
cases a blank is demanded such as demarcating the end of a
measure declaration.

(2) The free form nature of the code makes no restrictions on
the definition of a measure. This makes it possible to enter
notes within a measure that exceed the total number of beats per
measure. The nature of the program is such that if a mistake is
made for a single voice, the error is not propagated beyond the
measure. However, the error can be carried into the next
measure if looked at through The Visual Composer. I have added
a special function to the program that allows you to define the
number of beats per measure. This, combined with the definition
of a beat allows the program to alert you if a measure comes out
long or short.

(3) Use of articulation demands that the number of ticks per
beat be some multiple of three. More precisely, a short
articulation is equivalent to 1/3 of a sixty-fourth note. This
requires that a sixty-fourth note be split into three parts. If
a measure is a total of a whole note it requires 192 ticks to
define the measure. The integers used in a ROL file are signed.
This limits the total number of ticks that a voice can use to
about 32K. This means that the total number of measures that
can be contained in a piece is 32K / 192 or approximately 166.
This is still a pretty large number and I have seen only one
piece of music that I have done to this point that came close.
And it was still short by about fifty measures.

(4) Several parts of the coding system use hexadecimal notation.
In general this is not a problem since the system doesn't go
beyond a hex 'F'. In terms of translation of the notes this is
the simplest method. Believe me, it's not that difficult.

(5) AdMuse allocates 10K of buffer space to each of the eleven
voices. This was considered to be large enough to contain a
large song. Since the ROL storage conventions require four
bytes per note this means that a song can contain 2.5K notes
before it starts to overlap into another buffer. There are no
checks made to prevent this. See the section near the end of
this documentation concerning future features for considerations
in further releases of the program that will address this
AdMuse______________________________________________ Page 6
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


limitation.
.*..

AdMuse was not written to take advantage of any special color or
graphics capability. It is rather Plain_Jane in looks. In
fact, there was no attempt to make the program look busy when it
is chugging along. Besides the menu and error reporting there
is very little screen display. Despite the simplicity of the
display it does quite a lot.
AdMuse______________________________________________ Page 7
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Installation
============

AdMuse is a single program that only uses one support file. The
executable file is named ADMUSE.EXE. The support file is called
MUSE.CFG. This file will be provided when the program is first
executed.

Installation is as simple as copying the file either into a
working directory from which you will use it or into a directory
that falls within the environment's PATH variable. When you
execute the program the configuration file will be created. Be
aware that anytime you execute the program, if MUSE.CFG is not
in the current directory and the append command has been used to
specify a directory in which a file MUSE.CFG exists, the program
will draw its information from this file but create a new file
in the current directory.

The program is invoked by entering "ADMUSE" .
AdMuse______________________________________________ Page 8
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The Menu
========

Once AdMuse is invoked, the following menu is displayed



Available options are:

1.) Set file name
2.) Edit file
3.) Build .ROL file
4.) Change defaults
5.) Play song
6.) Unused
7.) Unused
.*..
8.) Shell to DOS
9.) Exit program

Enter option:

All options are single key. That is, you don't need to press
RETURN to initiate the option. The options are discussed in
detail in the following section. The coding system is discussed
after that.

Set file name
-------------

AdMuse maintains the name of a working file in the configuration
file. The name of this file is passed to the editor and the
player. When this option is chosen you see a screen similar to
the following.

---------------------------------------------------------------
Current source filename is

more.mus






Enter new name of source file [RETURN for no change]

--------------------------------------------------------------

If a file has been previously defined it is displayed in the
upper left corner of the screen. If you don't want to change
this, just press the RETURN key. (That would be the ENTER key
to a lot of you. I'm hard line on what I first called it). If
you want to change the name of the file, type in the new file
name and press RETURN.
AdMuse______________________________________________ Page 9
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The precise name of a file doesn't matter, as long you use
standard DOS naming conventions. The extension may be anything
you choose except "ROL". When you build a ".ROL" file with
option 3, the file name is stripped of any extension and the
".ROL" is appended. If you enter the source file with an
extension of "ROL" your source will be overwritten when the
output file is created.


Edit file
.*..
---------

Option 2 is used to invoke the user defined editor. The editor
is defined in option 4 below.

When the editor is called, it is passed the name of the source
file by the simple convention

editor source.nam

where "editor" is the name of the user defined editor specified
in the configuration file. "source.nam" is the name of the
source file. See the explanation under option 4 for a fuller
discussion on the nature of the source file name.

If the editor hasn't been defined an error message will appear
stating so. The user is then prompted to press any key to
continue. Otherwise, the editor is called. Should some problem
occur that prevents the editor from being run, another error
message will be displayed saying that the program failed in its
execution.

Once you've finished editing your source, exit your editor and
you will be returned to the menu.


Build .ROL file
---------------

This option begins the process of building the .ROL file. The
filename for the output file is taken from the name of the
source file. The file extension is replaced by ".ROL". The
directory into which the output file is placed is determined by
the appropriate entry in the configuration file (see option 4).
AdMuse______________________________________________ Page 10
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Two things can happen during the build process. The more
desirable is that no errors will be encountered and all you get
is a statement to that effect. If this message appears the .ROL
file will have been generated. Hit any key at this point to
return to the menu. The other possibility is that an error was
discovered. In this case the offending line is displayed near
the bottom of the screen with a marker pointing to the error.
In most cases the marker points directly to the character that
was responsible for the error. In the case of special functions
(those that are enclosed in parentheses) the pointer will
generally appear at the closing (right hand) parenthesis.

When an error is generated the compile process is stopped.
There is no attempt to recover from an error. Errors prevent
.*..
the generation of the output file. You will then need to press
a key to return to the menu then edit the file to correct the
error.

When a valid .ROL file is generated you may then use option 5 to
listen to the song, if you have a stand-along player available,
for testing.
AdMuse______________________________________________ Page 11
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Change defaults
---------------

Option for allows the user to define a number of defaults for
the program to use. The screen will look something like this.

------------------------------------------------------------
Input directory is

\muse



Default directory for input file

Default directory for output file

Default editor name

Default player

------------------------------------------------------------

The user is prompted for each entry in turn. The currently set
value for the option is displayed in the upper left corner.
Unlike with the entry of the name of the source file, you must
enter each of these in turn. Merely pressing RETURN does not
keep the previous defaults.

Default directory for input file
--------------------------------

This entry is used in conjunction with the name of the
source file to generate the full name to be passed to
the editor.

Default directory for output file
---------------------------------

When a .ROL file is being created, AdMuse first gets the
name of the source file and replaces the extension with
.*..
the string ".ROL". The resulting name is then combined
with the string from this entry to determine where the
output file will be placed. The same process is used to
create the name of the file that will be passed to the
stand-alone player.

The allowable length of this field is 127 characters.

NOTE: In both directory entries a RETURN causes the program to
use the current directory.
AdMuse______________________________________________ Page 12
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Default editor name
-------------------

This is where the user places the name of his ASCII
editor of preference. This field can accept up to 127
characters so you may specify a fully qualified path to
the editor. Otherwise, the editor must reside in your
default directory or else fall within the range of the
environment's PATH variable.

The editor specified should generate pure ASCII. The
program attempts to ignore all characters that fall in
the IBM extended character range and all control
characters other than carriage returns. This may let
some editors that embed such characters in their files
qualify for use.

Default player
--------------

This field accepts the name of any stand-alone player
program such as Tracy Harton's PLAYROL. The player
program must accept the name of the ROL file as its
argument

Play song
---------

This option triggers the default player defined in option 4
above. If the player program has not been specified, an error
message is displayed with a prompt to press any key to continue.
Otherwise, the player program is invoked and passed the name of
the output file generated by option 3. If for any reason the
system cannot run the player program (lack of memory, cannot
find the program) a different message will be generated
prompting the user to check the defaults. The player program is
invoked using the name of the player program followed by the
name of the .ROL file to play. The name of the song to play is
.*..
built up of the default output directory and the name of the
file that was created in option 3.

Depending on the circumstances, one of three things can happen.
Ideally, the song will play.

The second possibility is that a message will be displayed
stating that the player could not be invoked. This could come
from a number of causes. One is that there was not enough
memory to load the program. Another is that the program was not
found. If the player program depends on the sound driver being
loaded and is hasn't been, the player program will likely abort
without playing anything. In this case, exit AdMuse and load
the sound driver. Then re-enter AdMuse.

The third possibility is that the program will execute but
AdMuse______________________________________________ Page 13
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


return some sort of error. AdMuse cannot catch errorlevel codes
so the program may just flash by.
AdMuse______________________________________________ Page 14
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Unused
------

Options 6 and 7 are reserved for possible future use.

Shell to DOS
------------

Option 8 allows you to shell to DOS. This is provided in lieu
of currently un-implemented options for directory searches.
This option will create another DOS shell above the AdMuse
program. You can move around in the directories while in this
shell and modify files. To return to AdMuse, type "EXIT"
followed by the RETURN (ENTER) key. Keep in mind that any
directory changes made in the shell will be maintained when you
return to AdMuse. Any changes to the environment are not kept.

DO NOT use a DOS shell to load the sound driver. This will
louse up the memory management system and there will be no way
to allocate memory from AdMuse. Furthermore, doing this will
lock up the memory being used to run AdMuse and prevent it from
being used further until the system is reset.


.*..
Exit program
------------

As it says. This options gets you out of AdMuse.


How it works
------------

The general procedure with AdMuse is to edit a file using the
coding system described below. Save the file before exiting the
editor. Use the build option to look for coding errors and
generate the .ROL file if no errors are found. Use option 5 to
test the output. The player name defined in option 4 may be a
stand-alone player program such as PLAYROL or you may specify
the Visual Composer or Jukebox. However, with the latter two
options you're limited to their methods of obtaining and playing
the song which may take time and/or take more effort than you
wish to exert. Also remember that AdMuse remains in memory when
the player option is invoked which may take up too much memory
for larger songs to be played. AdMuse takes up less than 60K of
program space so there should be plenty of room for most files.

AdMuse______________________________________________ Page 15
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________



Now About the Music
===================

Some of the following discussion will be difficult to include in
a textual manner. I'll do my best to describe various musical
symbols. Nothing will replace a basic familiarity with music
notation. However, a very basic knowledge is all that is needed
to use this system to transcribe from sheet music to code.


Some music basics
-----------------

Music notation makes use of a series of five horizontal lines
and the intervening spaces. This is known as the staff. Each
line or space represents a note on the scale. The staff can be
marked as either treble or bass. The treble staff has a symbol
that resembles the ampersand (&) character with a spiral in the
bottom. The bass staff is denoted by a symbol that looks like a
backward lower-case 'c' with a drooping bottom. Each of these
symbols is referred to as a clef.

Notes on a staff with a treble clef fall above middle C (a term
referring to one of a periodic set of notes. More on this
.*..
later). Other symbols are placed on the staff to denote what
note is to be played. The shape and form of these symbols
indicate how long the note is to be played relative to the
duration of the other notes and the location on the staff
specifies what note is to be played.
AdMuse______________________________________________ Page 16
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


NOTE: The following figure represents the normal placement of
notes on a staff. It is NOT the notation that is used in the
coding system.

-A-
G
---------------------------------------F-----------------------

E
---------------------------------D-----------------------------
C
---------------------------B-----------------------------------
A
---------------------G-----------------------------------------
F
---------------E-----------------------------------------------
D
middle -C-
B

The above is the treble staff. Notes may extend above it and
below it. To handle notes below middle C a bass staff is used.
The following is a representation of the bass staff.

D
middle -C-
B
--------------A------------------------------------------------
G
--------------------F------------------------------------------
E
--------------------------D------------------------------------
C
--------------------------------B------------------------------
A
--------------------------------------G------------------------
F
-E-

Notice the correlation of the location of middle C. This is a
common point for both staffs. The same holds true for the
coding system. However, where in the normal notation system the
designation for the notes maintains the same progression, the
coding system reverses at middle C.
.*..

To relate this to the keys on a piano, if you look at the two
black keys in the middle of the keyboard, the white key to the
left of this pair is middle C. The white key to the right of
middle C is D, the next white key to the right is E and so
forth. The white keys are called naturals. The black keys are
either sharps or flats. Not all naturals have corresponding
sharps or flats. Naturals only go as high as G before they
begin over again at A. This is why the notes are grouped in
octaves.
AdMuse______________________________________________ Page 17
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


If you wanted to indicate that the note "G above middle C"
should be played, you would place a note on the second line up
of the treble staff. What symbol we place on the line
determines how long we hold the note. A whole note is
represented by a symbol that is an open circle. A whole note is
the longest single note that is represented by a single
character (longer notes can be held when a whole note is dotted.
Again, more of this later).

A half note is designated by an open circle with a vertical line
extending either up or down, depending on how high up the staff
it is placed. A half note is held for half the length of time
that a whole note is held. Quarter notes are the same as half
notes except that the circle is filled in. Not surprisingly it
is held for one quarter the time that a whole note is held.

Progressively we further have eighth notes, sixteenths,
thirty-secondths and sixty-fourth notes. Each of these is
represented by the same note as a quarter note except for a
flag dangling from the vertical line for each division by two.
That is, an eighth note has a single flag, a sixteenth has two,
a thirty-secondth has three and a sixty-fourth has four.


Using the code
--------------

Discussion beginning here will dwell on getting notes and their
durations into the code. It should be noted that there is a
certain degree of preamble required in the code before notes
should be entered but discussing the use of notes will make
clearer some of the other topics which will be discussed later.


Duration
--------

The following characters determine the duration of notes.
.*..

W Whole note
H Half note
Q Quarter note
I Eighth note
S Sixteenth note
T Thirty-secondth note
X Sixty-fourth note

When one of these characters appears in the code it means that
all notes following will be held for that duration until such
time as a new duration is declared.
AdMuse______________________________________________ Page 18
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The notes
---------

What notes are played are specified in a hexadecimal notation.
This means that single digit numbers are used that range from 0
to 'F'. In hexadecimal notation the regular digits 0 through 9
are what they look like. The letters 'A' through 'F' represent
the numbers 10 through 15. This notation makes it easy to
represent notes with a single character. At the same time,
restricting it to single characters like this does limit the
top-most note that can be represented. There are other methods
of reaching higher notes that will be discussed later. For the
moment it will be enough to present the following figure.

F
-E-
D
-C-
B
---------------------------------A------------------------------
9
---------------------------8------------------------------------
7
---------------------6------------------------------------------
5
---------------4-----------------------------------------------
3
---------2-----------------------------------------------------
1
-0-

This is the treble clef. Whenever the character '0' is
encountered the note middle C is played (with the provision that
the key signature doesn't say otherwise). If you enter the
character '4' it will cause a 'G' above middle C to be played.

.*..
The following code would play the scale.

I01234567

The character 'I' says play all following notes as eighth notes.
Each of the numbers play the notes 'CDEFGABC' where the note D
is represented by '1', the note E is represented by '2' and so
forth until C 1 above middle C is represented by '7'.

If we had entered

I0123Q4567

the first four notes would have been played as eighth notes and
the last four would have been played as quarter notes.
AdMuse______________________________________________ Page 19
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The bass clef is a sort of inverted treble clef.


-0-
1
---------2-----------------------------------------------------
3
---------------4-----------------------------------------------
5
---------------------6-----------------------------------------
7
---------------------------8-----------------------------------
9
---------------------------------A-----------------------------
B
-C-
D
-E-
F

Changing the clef
-----------------

The problem here is that we need a way to tell the program that
we want to use the bass clef. For this we introduce two new
symbols. When the program encounters the character '*' it means
that all the following notes are assumed to be on the treble
staff. The character '@' switches all following characters to
the bass staff. Notes posted to the bass staff are considered
to be negative. Treble notes are considered positive. For this
reason we use the plus (+) and minus (-) signs to force notes to
take values outside of their clef. Often, in music notation,
you will find a note that is written relative to its staff but
.*..
it falls outside of the five lines and four spaces. If this is
above the treble staff or even one line below it there is no
problem if the treble clef has been specified with the '*'
symbol. However, if the note we wish to play is below middle C
we can force it to act as if it were part of the bass staff by
placing a '-' in front of the note. The reverse can be done
when the bass clef has been declared by placing a '+' in front
of the note, forcing it to be considered as if it were on the
treble staff.
AdMuse______________________________________________ Page 20
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Examine the code

*Q01 @01

will cause four notes to be played at a quarter note duration
each. The first note played would be middle C. The second
would be D. The third would be middle C again and the fourth
would be B below middle C. If we wanted to do this without
changing the clef declaration we would enter

*Q010-1

Voices
------

So far this discussion has assumed only one voice. The program
is designed to handle up to nine voices. Although the AdLib
card is capable of handling eleven voices this is in percussive
mode. Since the original coding system did not account for
percussive voices, I have elected to default all voices to
melodic. There is a way to declare percussive mode but this
will be deferred until the section on special functions.

To determine what voice is being referenced we will use the
character 'V' followed by the voice number.

V1*Q4834 V2*IFDC85463 [email protected]

says that both voices 1 and 2 will be played in the treble staff
and voice 3 will be played in the bass staff. Specifying the
treble clef in voice 2 is not necessary. Clef declarations,
like durations, remain in effect until otherwise change.

Notice that the total time for each voice is the same. If we
consider this to be the content of an entire measure it means
that a measure has a total duration of a whole note. It could
be 4/4 (common time) or 8/8 or some such. If the piece we were
transcribing was more like 3/4 time we would have to be careful
to limit our total time to the equivalent of three quarter
.*..
notes.

Let's look at line above with some changes.

V1*Q4834 V2*IFDC854 [email protected]

What we have done is remove the last two notes in voice 2. This
does not create any major problems as long as the longest
duration of any voice represented does not exceed our intended
number of beats. Any voice that falls short of completing a
measure (i.e. is shorter than the longest voice) is padded with
rests to fill out the measure. The padding is done at the end
of the measure, never at the first.
AdMuse______________________________________________ Page 21
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


One note of caution. The program does not really care how long
you make a measure. The duration of one measure can vary from
the duration of the following measure. In terms of how the song
would play it makes little difference. However, if you were to
read the .ROL file into The Visual Composer , it could create
some imbalance. Measures might not begin where they are
supposed to. There are provisions discussed later on that help
to prevent this from happening.


Measures
--------

All right, we've talked about notes within measures and total
duration in a measure. Let's see how we delimit what a measure
is. We now present the character 'M'. When the program sees
this character it recognizes it as the beginning of a new
measure. The 'M' character may be followed by any number of
other characters up to a blank.

M23a V1*Q4834 V2*IFDC85463 [email protected]

All the characters up to the blank are ignored by the program.
The purpose of this is simply to provide a point of reference in
the event that a change needs to be made. I generally use
numbers exclusively. My use of the letter 'a' occurs when there
are variations in the repeat of a measure. I mark my sheet
music with successive numbers on each measure. In some songs a
part is repeated later in the piece. It is not uncommon for a
few of the notes to vary (usually indicated by smaller notes).
In order not to assign a new number to the measure I will use
additional letters as qualifiers. Again, this is for reference
only. It has no effect on the code.

When a measure is invoked several things take place. All
.*..
processing of any preceding measures is complete. Padding takes
place, if necessary, on voices in the preceding measure that
were not as long as the longest voice. The current key is
re-initialized. The voice is automatically reset to voice 1.
This is done as a convenience. The clef is not reset. The
above code could just as easily have been entered as

M23a *Q4834 V2*IFDC85463 [email protected]

with the V1 removed. There are other codes that force the same
processing. Anytime there is a change in the permanent key, a
change in the tempo, a new part is invoked or a repeat of a
previous part is called up the program will act as though it has
begun a new measure as this is the same thing as if it had
reached the end of a measure.
AdMuse______________________________________________ Page 22
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Parts
-----

In addition to measures, a piece may be broken down into parts.
In sheet music there are portions of the piece that are
repeated. It is beyond the scope of this text to describe the
use of Codas and such except that they are the equivalent of
programming GOTOs. In general you might find that your sheet
music has an introductory portion of a few measures followed by
the refrain. Other than the refrain there is the chorus. A
rather broad generalization would be that the lyrics of the
refrain change from one to the next. The chorus is usually the
same lyrics each time it is invoked. A common pattern might
look like

Introduction
Refrain
Refrain
Chorus
Refrain
Chorus
Ending

Each invocation of the refrain may have a separate minor ending
that would either lead it back into the next refrain or blend it
into the chorus.
AdMuse______________________________________________ Page 23
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


In the coding a part is marked by the character 'P'. Each part
.*..
is distinquished by a letter of the alphabet. This limits the
number of distinct parts to 26. However, a letter may be reused
if necessary.
.
.
.
PA INTRODUCTION
M1 *Q1234 V2*5678 [email protected]
M2 *Q4321 V2*876I55 [email protected]
PB REFRAIN
M3 .........
M4 .........
M5 .........
.
.
M12 ..........
PC BRIDGE OF REFRAIN TO REPEAT OF REFRAIN
M13 ..........
M14 ..........
PD RB REPEAT OF REFRAIN
PE BRIDGE FROM REPEAT OF REFRAIN TO CHORUS
M15 ..........
M16 ..........
PF CHORUS
M17 ..........
.
.
.
M18 ..........
PG RB REPEAT OF REFRAIN
PH BRIDGE FROM REFRAIN TO REPEAT OF CHORUS
M19 .........
M20 .........
PI RF REPEAT OF CHORUS
PJ ENDING
M21 ........
M22 ........
M23 ........
AdMuse______________________________________________ Page 24
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Repeats
-------

In the sample above we have also introduced the repeat character
'R'. When a part character is encountered any previous parts
are marked as ended and the new part is begun. The repeat
character is followed by the designation of the part to be
repeated. Invoking a part will automatically force an end of
measure process. Multiple repeats may be included within other
parts as the generation of the .ROL code is done recursively.
.*..
Be aware, however, that getting too complex with repeats may
cause the stack to colide with the program or data areas. The
use of the part designation before the repeat is generally to
simply force the end of the definition of the preceding part.
Invoking a repeat does not end a part. Attempting to repeat the
current part will generate an error message as will trying to
repeat a part that as yet has not been defined.


Key
---

So far our discussion has disregarded the key. Without a key
signature the default is the key of C. To specify a key we use
the character 'K'.

K1# or
K2& or
K2# or
K1& or
K

A '#" is the symbol for a sharp and the '&' is a flat. Looking
at a music staff you will usually see a given number of these
symbols. If three flats appear on the staff you only have to
specify "K3&". A 'K' that is not immediately followed by a
number is forced to the key of C. This is generally not
necessary since the default is C. However, some songs will
change key in the middle of a song. A 'K' followed by a number
between 1 and 7 must be followed by a '#' or '&'. The digit
following the 'K' must not be separated by white space. This
situation would force the key of C.

The program will place the appropriate sharps and flats on the
appropriate notes based on the key.
AdMuse______________________________________________ Page 25
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Accidentals
-----------

Any piece of music is apt to have notes that do not follow the
key. These are know as accidentals. If in the course of
transcribing a song, you encounter a note that is sharped or
flatted outside of the key you simply follow the note with a
sharp or flat symbol.

M23 *Q387#5 V2*4376 [email protected]

In voice 1 the note '7' is sharped. This will make this note a
sharp for the remainder of the measure. Note however that voice
.*..
2 also has a note '7' in it. This note will also be sharped as
a result of the prior '7' having been so. Note '7' represents
'C 1 above middle C'. This means that any C found after this
accidental will also be sharped. Notice the note '0' in voice
3. This '0' represents middle C. It too will be sharped even
though in terms of position on the staff it appears before the C
that actually received the sharp. In order to correct this,
assuming that there is no reason that it should be sharped, we
need to return it to its natural state. For this we use the
symbol for a natural, '%'. It is used in the same manner that
we would use a sharp or flat.

M23 *Q387#5 V2*4376 [email protected]%Q35

The natural notation can be used to either restore an accidental
to its proper, natural state, or to force a normally sharped or
flatted note to be natural for the remainder of the measure.

Any accidentals assigned in a measure remain in effect only for
that measure. A new measure restores the key to the state
specified in the latest key designation.
AdMuse______________________________________________ Page 26
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Articulators
------------

There is one other set of modifiers for any given note. These
are the articulators. These should follow a note immediately if
used. If a note is modified by an accidental the articulator
should follow the accidental notation.

An articulator is used to give a degree of staccato to a note.
The first articulator is the single quote, also know as an
apostrophe ('). This causes the note to be shortened by the
equivalent of one-third of a sixty-fourth note. A rest is added
to fill in the space. A longer articulation is achieved with
the double quote ("). This is twice the length of the short
articulation. As with the shorter articulation, a rest is added
to maintain the full length. Finally, there is the extended
articulator, the comma (,). This essentially cuts the length of
the note in half. A rest balances out the remainder of the
duration of the note.

A further enhancement may be forthcoming in a future version
that will permit the coder to begin an automatic articulation
for the current voice until it is toggled off. Articulation
causes two notes to be produced for each articulated note. It
also causes the number of ticks per beat to increase.


.*..
Dotted notes and triplets
-------------------------

Returning, for the moment, to the topic of duration, we need to
discuss two modifiers that may be applied. The first is the dot
(.). A dotted note plays that note for half again the duration
of the note. A dotted quarter note is held for the equivalent
time of three eighth notes, or, one and a half quarter notes. A
dotted half note is held for the length of three quarter notes.
The dot (.) must immediately follow the duration specification.

M30 *Q.1I3Q56

The above segment represents a total duration of a whole note.
The first duration is held for the length of one and a half
quarter notes or three eighth notes. The next duration is an
eighth note so our total is now four eighth notes or one-half.
The remaining two notes, each held for the length of a quarter
note round out a whole note.
AdMuse______________________________________________ Page 27
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The other modifier for a note's duration is the double dotted
note represented by a colon (:). This actually stands for a
triplet. A triplet is a set of three notes that are played in
the same time as two notes. The equivalent time for the note is
two-thirds of the base duration.

M17 *Q:345H6

The above has three notes played as a triplet. The total time
of the three notes is equivalent to a half note. The other half
note balances out the measure.

Double dotted and single dotted notation can be used in
combination with each other but the order has to be with the
double dot specifier first (e.g. Q:.). The reverse order will
generate an error.


Extending the note range
------------------------

As is probably obvious, there is a limitation to the range of
notes that this coding method permits. As is often the case the
notes go beyond the top limit of the coding scheme (+F) or below
the lower limit (-F). There is a method of extending this
range. This is by using the '^' operator. This character
causes the current voice to be raised or lowered. The syntax is
"^+#" or "^-#" where, in this case, the '#' is replaced by a
hexadecimal number from 0 to F. When this operator is
.*..
encountered it acts on the current voice only. It causes all
successive notes to be raised or lowered by the specified number
of whole steps (i.e. lines and spaces on the staff). In order
to return to the normal, non-transposed voice mode, use the
string "^+0".

This is usually a temporary action if used to stretch the range
of the scale. However, there is another use for this function.
Some sheet music is written for other instruments than piano.
These instruments may be soprano, tenor or alto in nature. By
making adjustments in these values a voice can be reserved for
these instruments and the notation transposed.
AdMuse______________________________________________ Page 28
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Transposing the scale
---------------------

There are two other characters that affect the final notes
played. These are the '>' and '<' operators. Placed in the
code they cause the entire piece from the point of their
invocation to raise or lower all the notes of all the voices by
the specified number of semi-tones. They are invoked by
entering either ">#" or "<#" where, again, the '#' is replaced
by a hexadecimal number such as ">4". This would cause all
notes to be played four semi-tones higher. "<2" would cause all
notes to be played two semi-tones lower.



Beat declaration
-----------------

The conventions used by AdLib's Visual Composer require that it
knows how many ticks there are to a beat. AdMuse calculates the
number of ticks per beat for you. However, it needs to know
what you consider a beat. That is where we use the 'N'
functions. This character needs to be followed by one of he
duration specifies H, Q, I, or S. No others are allowed.

NQ

says that a quarter note is considered to be equivalent to one
beat. This is also the default should this declaration be left
out of the code. Though it is not necessary to use this
function, since a default is provided, it is the only way to
make AdMuse recognize the basic tempo.

Which brings us to ......


.*..
Basic tempo
-----------


The basic tempo of the song is declared using the equal (=) sign
in combination with the 'N' function.

NQ=165

says that a quarter note is considered to be a beat and, when
playing at standard tempo, there will be 165 of them played each
minute. Again, there is a default supplied for the basic tempo
if it is not declared. This value is 120. This is also pretty
slow for most songs today.

Some sheet music will indicate in what tempo it was intended to
be played by putting a note at the top of first page followed by
the equal sign and the number of beats per minute.
AdMuse______________________________________________ Page 29
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


We'll see more of the equal sign later on. It has a further use
later on regarding tempo control.

Comments
--------

Last, and certainly least, we have the do nothing function.
What would a language be without comments? To begin a comment,
use the slash (/) character. All characters from that point on
to the end of the line will be ignored.

Comments are usually used to name the song, credit the author
and most importantly, credit the guy who entered all that code
into the computer. Hey!! How about that? It isn't so
do-nothing as I said.

The comment function can be useful in debugging code also.
AdMuse______________________________________________ Page 30
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The Special Stuff
=================


Most of the above is derived from the original coding format.
The AdLib card, however allows a much wider range of parameters
than the card for which this format was developed. The AdLib
card can handle volume, pitch and instruments on a per_voice
.*..
basis. I've also modified the meaning of one other command
mentioned above so that in another context it takes on a
slightly different effect. Most of the special functions appear
in parentheses. Keep in mind that this was done to be able to
extend the use of letters of the alphabet that have other
functions outside the parentheses. I also wanted to use the
parentheses to help improve readability and to provide
delimiters for the functions.

The special functions also generate a number of defaults under
certain conditions. For example, you may set a volume before
the first note of a song is declared and it will begin the song
at that volume. However, if you do not declare a volume within
the code, a default is assigned at the beginning of the song.
Also, if you enter code that generates notes then decide to set
a volume, the default volume will be generated at the beginning
of the song, followed by the placement in the song where the
volume is being declared.



Volume control
--------------
The first control function is volume. It may take several
forms.

1. (V#=.##)
2. (V#+.##)
3. (V#-.##)
4. (V=.##)
5. (V###+.##)

These are only some examples. The '=' operator takes the value
of the floating point argument on the right and applies it to
the voice number specified on the left of the '='. The right
hand argument must always be a floating point value between .01
and 1.00. The program makes no attempt to check the value of
the argument but will limit anything higher than 1.00 to 1.00.
Anything that goes negative will be changed to .01.
AdMuse______________________________________________ Page 31
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The argument on the left of the '=' operator specifies the voice
to which the operator and the right hand argument apply. You
may enter a list of many voices, each a single character ranging
from 0 to B. These are hex value where 'A' is equivalent to 10
and 'B' is translated to 11. As a means of short-cutting, the
value of '0' is used to specify all voices. Totally leaving
this argument off means that the program will perform the
operation on the current default voice.

.*..
The '+' and '-' operators will take the previous value of the
volume for the voice or voices specified and add or subtract the
value in the right hand argument. Checks are made to see that
the resulting value does not exceed the limits imposed by the
AdLib sound program. The default volume setting is .75.

When multiple voices have been specified, the position where the
volume change takes place is determined by the current voice and
applies to all voices that have been specified. If the change
to take place must be at the end of a measure, be certain to pad
the current voice with rests if the voice doesn't completely
fill the measure before declaring a volume change.


Pitch control
-------------

Little will be said about pitch control, other than the fact
that it works similarly to the volume function. The general
form of the pitch function is

(P[#[#[..]]] op floating_point_value)

The limit for the floating point value ranges from .01 to 2.00.
The default pitch variance setting is 1.00. A setting of 1.00
causes the instrument to play on pitch. Variations around this
value cause the pitch to play a percentage higher or lower than
the true pitch. A value of 2.00 will make an instrument play
the next octave up.

As with the volume, the exact timing of the pitch change is
determined by the current voice when multiple voices are
specified. All other caveats apply.
AdMuse______________________________________________ Page 32
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Instrument settings
-------------------

AdMuse allows for the setting of instruments by the following
special function:

(I[#[#[#]..]..]=instrument_name)

Just as with the volume and pitch functions, leaving out the
voice number cause the program to assume the current voice. The
reserved voice number '0' causes all voices to be affected.
Otherwise, you may use a single voice number or a list of voice
numbers. AdMuse checks for the length of the instrument name.
If it exceeds eight characters an error is generated and the
conversion process is aborted.
.*..

The default instrument is "piano1".

See volume and pitch information for restrictions concerning
exact timing of mutiliple voice specifications


Mode setting
------------

ROL files recognize in their structure two possible modes. The
first is the melodic mode. When a song is considered melodic it
can only access nine voices. The alternate mode is percussive.
Percussive mode recognizes eleven voices. However, five of
these voices are percussion instruments. In order to set the
mode the code recognizes the following formats:

(M=M) or (M=P)

where the 'M' on the left of the equal sign initiates the mode
function and the 'M' or 'P' on the right of the equal designates
(M)elodic or (P)ercussive mode respectively. The program
assumes melodic mode unless specified otherwise. While assuming
melodic mode or, if otherwise specifically declared, functions
that require that a voice be specified will generate an error if
a voice number greater than 9 is used. It is best to declare
the mode early in the code. Setting the mode also causes a
default set of instruments to be declared when the .ROL file is
generated if no instruments have been defined.

AdMuse______________________________________________ Page 33
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


The equate
----------

This is the function that has two meanings. Its major purpose
is to control tempo. It has been previously mentioned that when
used with 'N' function (set beats per measure) the basic tempo
is set. Once the basic tempo is set it may not be changed
again. Thereafter, all tempos are set as a multiple of the
basic tempo. These multiple are limited to the range of .1 to
10.0. If the basic tempo is not declared in the code (it is not
mandatory,) it defaults to 120 beats per minute. All tempo
events declared will be percentage parts of this basic tempo.
The form of the equate is simply

=##.#

where ##.# is a floating point value.

.*..
Two other forms of the function are

=+##.# and =-##.#

These, naturally, increase or decrease the tempo in relation to
whatever the preceding tempo was.

Tempo is a parameter that pertains to an entire song and not one
single voice. However, in order to be able to anchor the place
in the song where a tempo change takes place, AdMuse will assume
the position based on the current voice. Therefore, if the
function is invoked in the middle of the string defining the
notes for a specific voice, the tempo change will occur where it
is declared relative to the notes in that voice. Care should be
taken not to declare a tempo change late in one of the first
voices defined for a measure and early in a second voice. The
results would be unpredictable. AdMuse makes no attempt to
check for this sort of inconsistency.
AdMuse______________________________________________ Page 34
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Extended notes
--------------

Normally, AdMuse will end notes of a preceding measure when a
new measure is declared. In some songs, though, a note is held
over. This is designated in sheet music by a curving line
connecting the notes from one measure into the next. In order
to handle this, AdMuse uses the tilde (~) to indicate the hold
over note. A portion of code might look like this:

.
.
.
M12 *Q4536 V2*Q.8IAH9 ......
M13 *I6~Q.5Q32 V2*Q7875 ....
.
.

In measure 13 note 6 is followed by the extended note character.
This means that the note begun at the end of voice 1 in measure
12 will be carried over into measure 13 without being chopped
off. The total length of the note will be equivalent to a
dotted quarter note (Q.) or a quarter note plus an eighth note
as one note. If the note requires an accidental such as a sharp
of a flat, the tilde must follow the accidental.

REMEMBER: The tilde should follow the second note of the two.

If the two notes are not the same, there can be no carryover
between the notes. Music notation can have a curved line
.*..
between two such notes. This is known as a slur. AdMuse cannot
handle slurs at this time.
AdMuse______________________________________________ Page 35
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Beats per measure
-----------------

The 'N' character has been discussed previously. This is used
to define what note duration is considered a beat. AdMuse
calculates how many ticks make up a beat based on a number of
other considerations such as what the smallest note used is, if
the smallest note is dotted, if there are any triplets, any
articulation, etc. The AdLib Visual Composer uses a value in
the ROL file to specify the number of beats per measure. In our
coding format we will use the pipe (|) character for this
purpose. For example, by putting

NQ=165
.
.
|3

in the code, we say that a quarter note is considered a beat and
that 165 of them should be played every minute. There are three
beats to a measure (|3) making a total of three quarter notes
per measure. Once these are set, AdMuse will not allow you to
change them elsewhere in the song.

It is not necessary to specify any of the three parameters in
the song. There are defaults that will be used if none are
specified in the code. The value of a beat defaults to a
quarter note, tempo defaults to 120 beats per minute, and beats
per measure becomes 4. As far as this coding method is
concerned none of this really matters. The song will play
properly. However, if you use AdMuse to generate a ROL file and
then read it into the Visual Composer, if the values have not
been set, the measure and beat markers will not align properly.
This should be correctable by doing so from within the Visual
Composer.

A side effect of defining the size of a beat and the beat per
measure that AdMuse takes advantage of is that it now know how
many ticks there should be in each measure. If both parameters
are defined, AdMuse will issue a warning that a given measure is
too short or too long. This can be a great help in helping to
debug code where you type some extra notes or inadvertently use
the wrong duration notation. A warning does not abort the
process, as it isn't critical just how long or short a measure
is. There are some songs that change time signatures several
times.
.*..

Warnings may be repeated several times if they occur within a
part that is repeated. This is nothing to be worried about.
Fixing the problem will eliminate the repeated warnings.

As mentioned above, some songs have several changes in their
time signature. To eliminate all the warning messages, don't
declare the beats per measure until the end of the song.
AdMuse______________________________________________ Page 36
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Accentuation
------------

Note: The following feature is not currently implemented. It
is stated here in the event that you might want to include it in
your coding so that it will be there when accentuation is
implemented.

Accentuation is indicated in sheet music by a short greater than
sign (>) either above or below the note. This means that the
note should get a stronger attack than the other notes. The
character to be used for this will be the exclamation mark (!).
This character, when used as intended, follows the note to be
accentuated. If the note has an accidental modifying it, the
accentuation character should follow the accidental. If the
note is further modified by an articulator character, the
accentuation character should come before the articulator.

AdMuse will currently ignore this character when placed where it
is expected. It will also ignore it in most other places but,
if it is placed where AdMuse is looking for a modifier for
another function, it will undoubtedly generate an error.

When implemented, the use of the accentuation will add six bytes
to the file each time it's used.
AdMuse______________________________________________ Page 37
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Error messages
==============

AdMuse doesn't attempt to report more than one error message at
a time. An error message appears near the bottom of the screen.
The line with the error appears above the error message and the
position where the error was detected is marked with a check
above it.

.*..
Error messages are generally self explanatory. There is one
that is not quite as evident and deserves a quick word. An
error is generated when a voice is being declared, either as the
current default voice or as an argument in a special function
list, if the voice is out of range or not a valid hex character.
The problem is that the range is dependent on the prevailing
voice mode. Therefore, if the mode is the default, melodic, the
limit of any voice used is 9. The limit increases to 11 if the
mode is percussive.

Usually the error is marked precisely. The principle exception
to this involves the special functions that are enclosed in
parentheses. Due to the parsing that is performed on these
longer strings, the check mark will usually appear at the right
hand parenthesis. The associated error message will explain the
nature of the error. Narrowing it down should be relatively
simple.

One other warning that may be received concerns some limitations
imposed by the internal numbers that comprise a ROL file.
Numbers are stored as two byte, signed integers, This limits
the total number of ticks that a voice may play to something in
the range 32K ticks. To AdMuse, this looks like a negative
number. If the total ticks for a voice exceed this limit a
warning is issued and a number is displayed. The number should
be negative. The number has no significance except the fact
that it is negative. I would suspect that the Visual Composer
would blow up on this. Stand-alone players may treat the
numbers differently so you might stand half a chance of making
it play. Articulation on even one note could cause this warning
to occur. Removing it might solve the problem.
AdMuse______________________________________________ Page 38
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Composing hints
===============

The following suggestions constitute opinions that I've
developed over the years while encoding music. These are only
opinions and may not agree with your philosophy. Some pertain
to using this coding method and others are general observations.

-----------------------------

Always scan your sheet music in advance. Take notice of tied
notes. You may decide to disregard them at first, then go back
and insert the tildes where needed. Failure to tie notes may
make a piece sound choppy.

Plan your voices before you start to code. Know in advance what
notes will be assigned to what clef. If you can mark on your
.*..
copy of sheet music, draw colored lines between notes that will
belong to the same voice.

Play all notes. Some songs will go along for quite a while
playing only three notes in the treble clef then have a number
of fourth notes. These lend some expression to song and doesn't
have much effect on the size of the file.

If you own the sheet music from which you are transposing it is
a good idea to write a number above, inside or below the measure
and use the number in the measure declaration of your code so
that you can find it more easily if you detect something wrong
when you play the song. Or make a copy of it for marking on.

If a measure has a variation in it, that is, when the measure is
played again and one or more notes are change for the second
verse, you will need to define the measure as a separate part.
When the time comes to define the measure along with the
variation, use the same designation for the measure but append a
character that shows that it isn't the same as the first
declaration of the measure. For example, for measure number 23,
the first time the verse is played, mark the measure with "M23".
The second time the verse is played, with the variation, Mark it
as "M23a". This will help to keep things straight.

Don't be afraid to use comments to document your code. Comments
are ignored when the code is compiled but they can help you find
your position in the file. Use a comment whenever you change to
a new page. The comment should include the page number.

Also place blank lines between each set of measures on a line.
This also will help you find your position.
AdMuse______________________________________________ Page 39
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Place at least one blank space before the declaration of each
new default voice. Always redeclare the clef when changing to a
new default voice. This is not necessary except where the clef
changes but it will help you remember which clef is being used
and can improve readability by separating the number that
denotes the voice from numbers that declare notes.

Make use of the notation for beat definition and number of beats
per measure where practical. It will help with debugging.

Some songs may be improved by using articulation. Military and
march songs usually fall into this category. The main problem
here is that articulation automatically declares a sixty-fourth
note as being three ticks and depending on conditions concerning
dotted notes may double that feature. This doesn't prevent a
song from playing properly, but if viewed under the Visual
.*..
Composer the scale is magnified to the point of getting very
short portions of a measure on the screen.

Use the operators in the special functions creatively.
Crescendos and decrescendos can be implemented with the volume
function using the '+' and '-' operators. You can also use this
for fades at the end of songs.
AdMuse______________________________________________ Page 40
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Keep in mind that when a part is repeated, the information is
taken from the text at the point the part begins. Special
functions within a part are repeated along with the notes. This
can be used to advantage for such things as endings where you
want to do a repeat and fade. Use the minus operator sprinkled
inside the repeated part(s) to gradually reduce the volume.

Some songs begin with a measure that starts with a number of
rests. Though it is not necessary that these rests be declared
to make the song play on a stand-alone player, it is a good idea
to declare them in order to make notes align properly with the
Visual Composer's measure markers.

If a measure ends with all voices in a rest condition, pad one
of the voices to make certain that a full number of beats per
measure results.

Use the comment character to mask out lines you don't want to
listen to when checking a song. There are times when it would
be helpful to play a single measure or a string of measures over
and over while looking at the sheet music, looking for errors.

Be choosy with the songs you select. Some vocals sound great on
the radio but translate to pure instrumental poorly. The human
voice has a greater potential for expression than most
instruments and certainly more than those created by digital
techniques. Songs that are intended to be instrumental turn out
best.

Along the same lines, sheet music that is designated as a piano
arrangement may not lend itself well to using other instruments
in place of piano. Study the song and determine what voices are
used as fill-in. Some instruments with smoother sounds make
better fill-ins than those with abrupt attacks or decays.

Even a simple percussion pattern can improve the sound. Drum
out a cadence with your fingers and work out some relative times
for the various portions of the beat. Mix the percussion. Use
combinations of drums with cymbal type instruments or snare to
help break up the monotony
AdMuse______________________________________________ Page 41
.*..
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Make use of unused voices for special effects. The following
piece of code is used to produce a crescendo.


M35 *H12 V2*-1-1 [email protected]$A$A
v9*i(v0+.01)$(v0+.01)$(v0+.01)$(v0+.01)$
(v0+.01)$ (v0+.01)$(v0+.01)$(v0+.01)$

M36 *Q$$$5 V2*H0Q03 [email protected]$A$8
v9*i(v0+.01)$(v0+.01)$(v0+.01)$(v0+.01)$
(v0+.01)$ (v0+.01)$(v0+.0 1)$(v0+.01)$

Since voice 9 is not used, it can be used to produce more minute
changes in volume where voices 1, 2 and 3 use only quarter notes
as their smallest increments. The rests in voice 9 are used to
advance the timing. Specifying 0 as the voice in the volume
declaration causes all voices to increment despite the fact that
voice 9 is current. They all take on the timing of voice 9.
The increment is that of an eight note. Your ASCII editor
probably has the capability to reproduce the more tedious
portions of the code.
AdMuse______________________________________________ Page 42
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Common errors
-------------

If songs don't sound right, the following may help you to find
the error.

If the song as played by a standalone player doesn't sound
right, make sure that the sound driver has been invoked with a
sufficient buffer size.

If a measure sounds long and seems to play extra notes, make
sure that you have properly declared a new voice where needed.
Sometimes a voice declaration is repeated inadvertently in the
same measure.

Long or short measures can occur as a result of not specifying a
change in the duration. When the length of a note is declared,
it remains in effect until a new declaration is made. This is
true even between voice changes and measures. Sometimes, when
modifying code, something is inserted that includes durations
declarations. This may come between two portions of code where
the duration was assumed to be unchanged so no change was made.
.*..

Musical clunkers may result from a failure to change the clef or
in declaring the wrong clef.

If volume, pitch and instrument changes seem to cause the song
to demonstate extreme, unexpected changes, there might be some
attempt to cross declare them. Make sure that all such changes
don't logically occur in a manner that may have them out of
sequence. For instance:

M23 *Q783(V12+.05)5 V2*(V+.03)7395

The first volume change in the example above is declared in what
amounts to near the end of the measure. This causes the change
for voice 2 to occur at the same point. But the second change,
declared when voice 2 is current, says to make the change at the
beginning of the measure. So, in terms of sequence of events,
the second change should occur before the second. However,
since the sequence in which it is declared causes it to do other
wise, the information is stored in the improper order.

There are a couple of ways of working around this. One way is
to declare voice 1 after voice 2 as in:

M23 V2*(V+.03)7395 V1*Q783(V12+.05)5

or the components of voice 1 can be split up

M23 *Q783 V2*(V+.03)7395 V1*(V12+.05)5

or specify the volume changes relevant to voice 2 independently.

AdMuse______________________________________________ Page 43
___AdMuse__________________________________February 12, 1990___

________________________ Documentation _______________________


Future Features
===============

The following are considerations for future features. Some may
be implemented and others may not, depending on the
practicality.

1. Automated crescendos. Decrescendos also.

2. Mapping of preset volume levels. Music notation
recognizes certain letters that show what the volume
level should be at a given point. The user should be
allowed to define what these levels will be, then mark
where in the song the volume changes to any of the
preset values.

.*..
3. Pitch bending effects.

4. Attack accentuations for expression.

5. Pre-defined bass or percussion patterns. These would
then be used in a repeating fashion to eliminate
unnecessary typing.

6. Voice duplication. The user should be able to specify
that all notes for a given voice will be automatically
duplicated in another voice. This, combined with pitch
variation would provide for richer sounds.

7. Directory searches.

8. Listing instruments in a user defined instrument bank.

9. Copy and delete functions.

10. Chord notation. Might be able to simulate guitar
strumming.

11. An option allowing the user to define the length of the
buffers used to store the note information.

12. Color options for those who absolutely need to have
them. Maybe some windows, maybe not.
AdMuse______________________________________________ Page 44




AdMuse
Registration Form

Mail check or money order to:

Robert A. Calbridge
12904 Elam Road, Apt 101
Balch Springs, TX 75180

Please do not send cash in the mail


Please fill in the following information

Your name

_________________________________________________

Adress

_________________________________________________

.*..
City, State, Zip

_________________________________ _____ __________

How much are you enclosing? $________


Where did you get AdMuse? ______________________


Comments or suggestions

________________________________________________________________

________________________________________________________________

________________________________________________________________

________________________________________________________________


AdMuse
Copyright (C) 1990, Robert A. Calbridge, Jr.