MUSIC.DOC file
                              by Jeff Broido

               Copyright 1990 by Broido Computer Consulting.
                All rights reserved.  The right is granted
                    to anyone to copy these materials,
                        but they must not be sold.


OVERVIEW
--------

The MUSIC application allows the user to play simple non-polyphonic themes 
on the HP48SX calculator.  Several sample melodies are included, and any 
user with a rudimentary knowledge of music can add more.  While the song is
playing, the title, key and optional rolling text are displayed.

This system was developed on an HP28S.  If there is any interest in the 
original version (which is only slightly different), please attach a 
response.  Note that the HP28S, although slower and less able to play 
themes up to tempo as a result, has a cleaner tone transducer.  The 28 
sounds like a flute; the 48, though I dearly love it, sounds to me like a 
diseased duck.

PROCEDURE
---------

 1. Using Kermit, load MUSIC into any HP48SX directory.  the MUSIC 
    directory will appear as a sub-directory of whatever directory is 
    current when the file is transferred.  For your reference, the BYTES 
    command yields a checksum of # FF77h and a size of 10837 bytes.

 2. Press [MUSIC] to switch to the new sub-directory.

 3. Enter a number from 0 to 10 and press [PLAY].  The title, key and 
    optional information will appear as the song is playing.

 4. To stop a song while it is playing, hold down the enter key long enough
    so that it is still depressed at the transition point between any two 
    notes.  

 5. To make a song repeat endlessly, hold down the R (for repeat) key (the 
    right arrow) until "Repeat Mode." appears on the third line of the 
    display.  To cancel repeat mode, hold down R again and the song will 
    end at its normal point.  Don't hold down R too long in any case, or 
    the calculator will make a strangled, gargling noise.

 6. To get a listing of the songs in your MUSIC directory, hit the [CAT] 
    key.  This takes a while, and formats the list in the graphic array, 
    PICT.  If you have eleven or more songs, you can use the up and down 
    arrows to scroll around in the list.  If you haven't done any graphics 
    work since running CAT, you can redisplay the previous list by hitting 
    [CREV] (for "catalog review").  To exit from the catalog display, hit 
    ATTN (the ON key).

 7. The system is shipped to you in the key of C.  To change keys, hit 
    either [A], [C], [Eb], [F] or [G], which you'll find beginning on the 
    third menu page.    


SYSTEM DESCRIPTION
------------------

This system is very simple, as befits anything that purports to make music 
with the beeper on a calculator.  There are two main programs, PLAY and 
PLAYD.  The former runs at normal speed and the latter is somewhat slower, 
as it displays sequentially the list position of the note or text object 
currently being processed.  The programs are almost identical.  The reason 
I didn't use a switch to control this display and one program is that even 
the small block of IF-THEN code used to check the flag is enough to slow 
the program down appreciably.  The slower the program, the larger the ratio
of the time between the notes to the notes themselves.  As it is, one can't
program really short notes properly.  You can make the beeper sound for a 
short time, but you can't make the sum of this short time and the time 
between one note and the other arbitrarily short.  This results in a rubato
staccato effect which is not at all pleasing.  PLAYD is mainly for 
debugging new themes.  If you're not going to create your own, you might as
well purge PLAYD.

The themes themselves are in variables with names consisting of a degree 
sign (alpha-right-shift 6) followed by from one to three numeric digits.  
The contents of any of these variables is either a list or a program which 
when evaluated leaves a list on the stack.  The former is for simple 
melodies, and the latter is for complete songs with, perhaps, an a-b-a 
structure.  The a and b parts are included only once, and put together into
their final form as one long list.  See song number 7 for an example 
(variable '³7').  The default theme, in case you hit [PLAY] without 
specifying one or specifying one that doesn't exist, is the first theme of 
the fourth movement of Brahms' first symphony.  This is in variable ³0, so 
be sure not to delete it.  If you don't want to keep Brahms' lovely theme, 
make sure you replace it with something else.

The first element of any of these theme lists is an integer representing 
the tempo.  Ideally, it is the number of duration-one notes which will be 
sounded per second.  The second element is a string containing the song's 
title; anything over 22 characters will be truncated.  The third and 
subsequent elements are notes and optional text strings to be displayed 
below the title when they are encountered as the song is playing.  

The notes consist of a pitch value, which is an integer from 1 to 29 
(representing almost two and a half octaves), and an optional duration.  If
the note is a scaler, it's duration is assumed to be one.  If it's complex,
the real part is the pitch value and the imaginary part is the duration.  
In either case, if the pitch value is 0, the note is a rest (it pauses for 
the duration value but produces no sound).  For example, if we're in the 
key of C, and you want a tempo of three quarter notes per second, the title
of the song is "Blumphwitz Schnorg", and it consists of a half note middle 
C followed by quarter notes E and G above middle C then eighth notes B and 
D and finally a dotted half note C above middle C, you'd code it like this:
{ 3 "Blumphwitz Schnorg" (1,2) 5 8 (12,.5) (15,.5) (13,3) }.  If all of 
this seems confusing, look at the eleven examples and play around with your
own.  You'll discover that the timing is more difficult than my example 
since the slowness of the calculator and interpreter makes short notes and 
rests take longer than they should as I explained above.  

The absolute pitch values are found in an array called SCAL, which is 
generated when you change keys by program SC.  The key changing programs A,
C, Eb, F, and G simply stuff a starting value and key name into the list 
called ORIGIN, call SC to create the scale on the stack, and store it in 
SCAL.  If you want to use a scale starting at an arbitrary frequency, just 
save this starting frequency in ORIGIN (it doesn't have to be a list), hit 
[SC] and store the result in SCAL by hitting left-shift-[SCAL].  You can 
determine a proper scale starting value by using one of the existing 
programs to establish a scale and then examining SCAL and counting up until
you find the note you want.  You can then model a scale changing program on
mine using the new origin value.  I should mention at this point, in case 
you notice, that my Eb (for E-flat) doesn't use a lower case b for the flat
sign, but some obscure symbol (169 CHR) which might be an old english 
thorn; it looks more like a flat symbol.  The last thing to mention is 
variable DUR.  You can change this to speed-up or slow-down all tempos 
without modifying the tempo elements in all of the theme lists.  It is 
shipped with a value of .2.  Larger values will slow the tempos and vice 
versa.  

Good luck with this system.  If you want to discuss it, or wish to 
contribute any of your own themes, you can call me at (201) 455-0362 or 
leave a note and/or attachment for downloading on the HP Calculator 
Bulletin Board.
                                                   Jeff Broido