MusicBox 2.01

by Tan Kok Mun (kokmun@pacific.net.sg)
Copyright (C) 1996

The latest version of this software and additional music compilations
can be found at :

     http://home.pacific.net.sg/~kokmun/basic.htm


THIS IS A FREEWARE. If you like this software, post me an e-mail or a
post card. If you want to send money, please send it to your local
charity.


0. HISTORY
   21/05/1997 - Updated to make it cbaspad 0.77 compatible.

   04/01/1997 - Corrected CSV file import problem for MAC user.

   24/12/1996 - MusicBox 2.0
                - Corrected the relation between Tempo, Note Length and Note Playtime.
                  The music should sound more controlled now and at an even tempo.
                - New Installation method for the BASIC program and MusicBox Collection.

   13/12/1996 - MusicBox 1.1
                - Enforce MusicBox header. The memo title must have the
                  following header format:
                     !<song_title>
                  When prompt for song to play, "!" must not be entered
                  this will be inserted by the program.
                - Fix QUIT from program logic.
                - Does not end after a song, it will now prompt you
                  for the next song to play.
                - Added invalid MusicBox format detection. If it detects
                  more than 10 invalid characters in the memo it will be
                  treated as an invalid MusicBox format.
                - Support the note suffix ".". The old method of setting
                  the note length before and after the note cause more
                  overhead.
                - Support for Music setting, which is slightly different
                  from QBasic. See documentation for detail.

                QBasic to MusicBox Converter 1.1
                - Support for note suffix ".". It no longer change the
                  ".' suffix to add note duration before and after the note.
                - Better file detection.
                - Support space memo header name


   11/12/1996 - MusicBox 1.01
                QBasic to MusicBox Converter 1.0


1. LEGAL INFORMATION/DISCLAIMER

   Please understand that you use MusicBox at your own risk. I cannot 
   be held liable for damage or any lost in productivity due to the
   usage of MusicBox.

   BY USING MUSICBOX, YOU ARE AGREEING TO BE BOUND BY THE TERMS
   PRESENTED BELOW:

   You expressly acknowledge and agree that use of the MusicBox
   software (hereafter referred to as 'the Software') is at your sole 
   risk. The Software and the related documentation are provided AS IS  
   and without warranty of any kind, express or implied, including, but 
   not limited to, the implied warranties of merchantability and fitness 
   for a particular purpose.

   Under no circumstances, including negligence, shall Tan Kok Mun be 
   liable for any incidental, special or consequential damages that result  
   from the use or inability to use the Software or related  documentation, 
   even if advised of the possibility of such damages.


2. INTRODUCTION

   Before I begin, I will like to say that I'm not music literate. This
   program was written after searching the INTERNET and experimenting
   countless hour with QBASIC and pilot BASIC. Hence I believe there might
   be some missed play of the music.

   As I go along, I will appreciate anyone who knows more music than me,
   do correct my mistake by letting me know.

   The Music Box program is a program which you can use to play music that
   you have composed. You compose your music in the memopad. The music is
   stored in the memopad in ASCII format. You may want to create a seperate
   category in your memopad (eg. "MusicBox") to keep everthing neat.

   The first line of the memo will be the name of the song. Please see
   sample below. It has to begins with a "!". You are also advise to sort
   your memopad, either using the MEMOSORT program or SuperPad. This will
   move your music to the beginning of the memo internally. This will help
   to speed up MusixBox searching speed when looking for the song you want
   to play.

   To see that it is at the beginning, select the ALL category and you
   should see your music as the first few on the list. "!" when sorted
   comes before any alpha characters.

   Example of looney tune :

      !looney
      M1T200L8O3E.L16DL8CDEdECDDDL2D.L8D.L16CL8<B>C
      DcD<B>CCCL2C.L8<G.L16gL8A.L16gL8G.L16gL8
      A.L16gL8G>DDL2D.L8<AgAL4>DEL2G

   You need to enter all in uppercase, lower case is used to mean a sharp
   note, please see below.

   The format of the note is very similar to QBASIC PLAY command, if you
   know the QBASIC PLAY, then you will not have much of a problem
   understanding this.

   This is taken directly from QBASIC HELP on PLAY. I will mention things
   that is not supported currently. The reason it is not supported is
   because I do not know what it is. Maybe you know, and I appreciate if
   you let me know what it is.

   Octave and tone commands:
     Ooctave    Sets the current octave (0 - 6).
     < or >     Moves up or down one octave.
     A - G      Plays the specified note in the current octave.

     Nnote      * NOT SUPPORTED *
                Plays a specified note (0 - 84) in the seven-octave
                range (0 is a rest).


   Duration and tempo commands:
     Llength    Sets the length of each note (1 - 64). L1 is whole note,
                L2 is a half note, etc.

     ML         Sets music legato.   M1 in MusicBox format.
     MN         Sets music normal.   M2 in MusicBox format.
     MS         Sets music staccato. M3 in MusicBox format.

     QBASIC NOTATION   MUSICBOX NOTATION
     ---------------   -----------------
     ML                M1
     MN                M2
     MS                M3

     Ppause     Specifies a pause (1 - 64). P1 is a whole-note pause,
                P2 is a half-note pause, etc.
     Ttempo     Sets the tempo in quarter notes per minute (32 - 255).

   Mode commands:
     MF         * NOT SUPPORTED * Plays music in foreground.
     MB         * NOT SUPPORTED * Plays music in background.

   Suffix commands: Only "." is supported, "#","+" and "-" are supported 
                    in a different format, PLEASE READ NOTE BELOW.
     # or +     Please see note below. Turns preceding note into a sharp.
     -          Please see note below. Turns preceding note into a flat.
     .          Plays the preceding note 3/2 as long as specified.

   To indicate a sharp note, you use the lower case of the note, instead of
   "C#" or "C+", you enter it as "c". For flat note (suffix with "-"), you
   have to use the sharp note equivalent.

   See table below :

     QBASIC NOTATION    MUSICBOX NOTATION
     ---------------    -----------------
     C# or C+ or D-     c
     D# or D+ or E-     d
     F# or F+ or G-     f
     G# or G+ or A-     g
     A# or A+ or B-     a


   I have included a QBASIC PLAY TO PILOT MUSIC BOX conversion program, 
   this will convert the QBASIC PLAY to MusicBox format, ready for export 
   to memopad. This only runs in MSDOS only.

   Before using the converter, you need to strip off any program logic.
   Remarks are ok and so is the PLAY command that is left in the program.

   The following QBASIC PLAY program can be converted successfully :

      'Popeye
      PLAY "MNT150L8O3EGGGL4FL8EL2GP8L8GAFAL4>CL8<AL2GP8L8GAFA>C<B"
      PLAY "AGAGECEGGGL4AL8BL2>C."

      REM Looney Tunes
      PLAY "MST200L8O3E.L16DL8CDED+ECDDDL2D.L8D.L16CL8<B>CDC+D<B>C"
      PLAY "CCL2C.L8<G.L16G+L8A.L16G+L8G.L16G+L8A.L16G+L8G>DDL2D."
      PLAY "L8<AG+AL4>DEL2G"


3. SYSTEM REQUIREMENTS

   All the files here requires the excellent Chipmunk Tiny Basic for Pilot
   written by :

      Ronald H. Nicholson, Jr.

   If you don't have it and will like to try out this FreeWare program
   please get the Chipmunk Tiny Basic from :

      http://www.nicholson.com/rhn/pilot.html

   Version 0.57 of cBasPad or higher is required.

      
6. INSTALLATION & RUN

   Please refer to INSTALL.TXT for installation information.

   To run the BASIC program, after you have selected cbasPad you will see a
   summary of all the BASIC program that you can run. Select one of them and
   press "EXEC" to run it.


7. USING MUSICBOX

   Import the SONG.CSV to your PILOT DESKTOP MEMO using the IMPORT FACILITY.

   When you run the MusicBox, it will prompt you for the song name, this is
   the name that appears as the first line of your music score. Just
   remember, it is case sensitive. Do not enter the "!", this will be
   inserted by the program.

   If you enter "william" as the song to play, the program will look for
   "!william" from the memopad.

   If you need to stop the song before it finishes, press <DONE> button.

   To get louder volume from your PILOT, place it flat on a hard flat
   surface when playing the music.


8. FREEWARE AGREEMENT

   MusicBox is a freeware. However this does not mean that you own the
   software code, you are only licence to use it. All ownership and Copyright
   of the software and code belongs to Tan Kok Mun. Please read LICENSING
   AGREEMENT below.

   
9. LICENSING AGREEMENT

   The software accompanying this document (the Software) and the related  
   documentation are licensed to you by Tan Kok Mun (the author).
   
   Although the Software is freeware, it is not Public Domain. The software 
   contains copyrighted material and other proprietary material. 

  
10.DISTRIBUTION

   This manual and all accompanying files may be distributed freely,
   provided that:
   - Neither text nor any other file is modified in any way. No file
     may be omitted nor added in the distribution.

   - No money may be charged for the program nor for any accompanying
     files, other than the usual downloading time fees charged by
     commercial BBSes and online services.

   - I want to know where my program will be distributed. Please notify me
     if it will be included in printed matter, floppy, or CD-ROM before its
     publication. No matter what the circumstance, I would strongly
     appreciate a copy of whatever collection in which it is included.

   - If you distribute any program that is based on this program, you must
     not charge anything for them. In addition, you must attribute their
     origin: please describe them as having been made by this program.
     (e.g.: "This program is based on the Loan Calc written by TanKM").
     When they are published in a commercial magazine or book,
     they must be described as having been made by this program, and the
     author requires the contribution fee determined by the magazine or
     book company. In these cases, please contact the author to get
     permission before publication.


11.CONTACTING THE AUTHOR

   If you should wish to reach me for any reason, including, but not
   restricted to:

   a) Bug reports.
   b) New features request.
   c) Modifications to existing features.
   d) Any comments, good or bad.   8-)
   e) Greeting Cards.

   I can be reached at:

   E-Mail     : kokmun@pacific.net.sg
   Web Page   : http://home.pacific.net.sg/~kokmun/

   Snail-Mail : Tan Kok Mun
                64, Jalan Kuak
                Singapore 577833

