
                     WHISTLE -- Play a Tune on your PC

         program and documentation by Stan Brown, Oak Road Systems
                           revised 4 August 1999
            Copyright 1998-1999 by Stan Brown, Oak Road Systems
     _________________________________________________________________

   WHISTLE will play a tune on your PC's internal speaker, without a
   sound card.

   ______________________________________________________________________

                                  Contents
   ______________________________________________________________________

   What is WHISTLE?
   License and warranty
   Installation
   User instructions
   WHISTLE with an input file
   WHISTLE without an input file
   Examples
   Music language
   General rules for input
   Lyrics
   How to code notes:
         Pitch of notes -- Duration of notes -- Tied notes -- Trills
   Rests (R and P commands)
   Octave selection (O, ^, v, >, and < commands)
   Key signature (K command)
   Timing (T and L commands)
         L for duration -- T for timing
   Style and phrasing (M commands)
   Summary of music commands
   Revision highlights

   ______________________________________________________________________

                              What is WHISTLE?
   ______________________________________________________________________

   Even in these days of SoundBlaster, there are still perennial requests
   on the newsgroups for a program to play a desired tune using the PC
   speaker.

   WHISTLE meets that need. I use it to play a short fanfare when my tape
   backup has finished; I have also used it to reproduce extended
   selections from some of my favorite pieces -- just to prove that I
   could.

   I designed WHISTLE's music language by extending the language of the
   PLAY statement in old PC-BASIC, from the days of the original IBM PC.
   My extensions include
     * synchronous display of lyrics
     * key signatures, naturals, double sharps, and double flats, so that
       you can code a piece of music exactly as it's printed
     * phrasing and tied notes

   DOS 3.1 or higher is required. WHISTLE will also run in a DOS box
   under Windows 95 or 98. I haven't tested it under Windows NT, but a
   friend ran a quick test and said it worked for him.
   ______________________________________________________________________

                            License and warranty
   ______________________________________________________________________

   WHISTLE is shareware. If you use it past a 30-day evaluation period,
   you are morally and legally bound to register and pay for it. Please
   see the file LICENSE.TXT for full details, including support and
   warranty information.

   ______________________________________________________________________

                                Installation
   ______________________________________________________________________

   There is no special installation procedure. Simply move WHISTLE.EXE to
   any convenient directory in your path. If WHISTLE.EXE is not in your
   path, you can always run it by specifying its location explicitly, for
   example:

        d:\utility\music\whistle
   ______________________________________________________________________

                             User instructions
   ______________________________________________________________________

   WHISTLE takes one optional command-line argument, the name of an input
   file.

  WHISTLE with an input file

   If you specify a filename on the WHISTLE command line, WHISTLE will
   read that file for statements in WHISTLE's music language. If you
   specify a filename without extension, WHISTLE will look first for that
   name and then for that name with the extension ".MUS".

   Example:

        whistle c:\somedir\beaches

   Please note that WHISTLE doesn't understand long filenames. If you
   want to pass it an input file that has a long filename, just use the
   "MS-DOS name" (short filename equivalent), which you can find by
   right-clicking the file in Explorer and then selecting "Properties".

   To interrupt WHISTLE while it's playing an input file, just hit
   Ctrl-C. WHISTLE my finish the current input line and one more before
   it stops. (If you have redirected output to NUL, you may not be able
   to stop WHISTLE until it has played the whole input file.)

  WHISTLE without an input file

   If you invoke WHISTLE without specifying a file, it will read music
   language from standard input. You can then type input lines as you are
   prompted. To end your input, enter a blank line, Ctrl-Z, or the F6 key
   followed by Enter.

   If you want to play a short tune, especially in a batch file, you can
   put it right on the command line like this:

        echo o4 t240 ceg^c2vg^c2 | whistle >nul


   ______________________________________________________________________

                                  Examples
   ______________________________________________________________________

   You will find several extended examples in the ZIP file: look for
   files with the extension MUS.

   ______________________________________________________________________

                               Music language
   ______________________________________________________________________

   WHISTLE's music definition language is based on that provided with IBM
   Personal Computer BASIC and similar BASICs, but has many enhancements.
   Any play string that is accepted by those BASICs should work fine with
   WHISTLE. (Does anybody even have any old PC-BASIC programs around?)

  General rules for input

   Music strings can be in caps, lower case, or a mixture. (I show letter
   commands in caps to make them stand out.) You can sprinkle spaces
   freely for readability, since spaces and tabs are ignored. The
   components of an input line are interpreted from beginning to end, and
   WHISTLE simply ignores anything it doesn't understand.

   Music strings contain notes, rests, and setup commands. (Input lines
   can also contain lyrics; see below.) Setup commands are so called
   because they set some condition or default such as tempo, key
   signature, octave, or style and phrasing. Setup commands stay in
   effect until you change them; there is no need to repeat them on every
   line of the file.

   Normally you would begin your input file by selecting an octave, a
   tempo, and most likely a key signature.

  Lyrics

   You can put the lyrics for a line at the end of that line, like this:
        g2b.b8e2. fgab>c<f2.p ; O Canada! Our home and native land!

   The semicolon tells WHISTLE to display the rest of the line on screen
   and not to try to play it as music. (You can use a colon instead of a
   semicolon, if you prefer.)

   WHISTLE will display the lyrics as it begins playing the first note on
   the line. From the user's perspective, that makes the lyrics look
   synchronized with the tune.

   If you have a long line, you may want to have WHISTLE display short
   phrases synchronously with the tune, building up the complete line in
   several stages. To do this, end each phrase except the last with a
   backslash, like this:

        g2b.b8e2. ; O Canada! \
        fgab>c<f2.p ; Where pines and maples grow,

   The phrase "O Canada!" will appear on screen and those notes will
   play. Then "Where pines and maples grow," will appear on the same
   line, and those notes will play. The next lyrics, whatever they may
   be, will appear on a new line.

   It's legitimate to have lines containing only lyrics, for instance
   when giving title information or to create a blank line on screen
   between stanzas.

  How to code notes

   A note has both pitch and duration. Examples of notes are A4 (a
   quarter-note A), C#2. (a dotted-half-note C-sharp), and B- (a B-flat,
   played for a duration set by the most recent L command; see Timing,
   below).

      Pitch of notes

   The basic pitch is a letter A through G, in upper or lower case,
   optionally folowed by an one of these accidentals:
     * sharp, # or +. Example: C# or C+ means C-sharp. B# and E# are the
       same frequencies as C and F, just as on a piano.
     * flat, - (hyphen). Example: B- means B-flat. As on a piano, C- and
       F- are the same freqencies as B and E.
     * natural, /. The natural sign is needed only when a key signature
       is used (K command, below). For example, if the key signature is 3
       sharps, then every F, C, and G is automatically sharped. In this
       case, if you need a C, F, or G natural, you can code it as C/ or
       F/ or G/. (If the key signature is 3 sharps, and you code a G-,
       you get G-flat as always.)
     * double sharp, X or x. Example: GX means G-double-sharp, or A.
       Double sharps aren't really necessary, since there's always an
       alternative way to code them. But if you're following a piece of
       printed music that uses them it's a convenience to use the same
       notation.
     * double flat, _ (underscore). Example: A_ means A-double-flat, or
       G. As with double sharps, double flats are a convenience rather
       than a necessity.

   Remember that most pieces of music have very many more sharps or flats
   than you see on the printed page: they are implied by the key
   signature. You should code the input to WHISTLE by using the same key
   signature (K command, below); otherwise you'll have to code those
   hidden sharps or flats explicitly.

   The note letters run C through B for each octave. The O command
   (below) sets a specific number; the ^, v, >, and < commands (in the
   same section) move up or down an octave from the previous setting.

      Duration of notes

   The duration of a note can be coded after the note letter and any
   accidental, using a number 1 or higher. For instance, C1 is a
   whole-note C, and F#16 is a sixteenth-note F-sharp. (A 1 always
   indicates a note four times as long as a quarter note. This is
   different from some music notation that uses a whole note for a whole
   measure, even in 3/4 time.)

   You can use dots as in normal music notation: E2. is a dotted half
   note as long as three quarter notes, and A4.. is a double-dotted
   quarter note, as long as seven sixteenth notes.

   To code triplets, multiply the duration number by 3/2 (which is
   equivalent to dividing the actual playing time by 3/2). For instance,
   eighth notes have duration number 8. Therefore eight-note triplets
   have duration number 8 times 3/2, which is 12. Why 3/2? Because the
   three triplets occupy the time normally taken by two notes.

   It can save you some typing to notice when most notes in a piece, or a
   section of a piece, are of the same duration. In this case, use the L
   command (below) to set the "normal" duration of a note; then you need
   type durations only for the notes that are exceptions. For instance,
   after L4 the string A2BG.F represents a half-note A, a quarter-note B,
   a dotted-quarter-note G, and a quarter-note F.

   The actual time a note is played depends on both the duration number
   coded with the note (or in an earlier L command) and on the tempo (T
   command, below). For instance, a quarter note at T60 is played for a
   second, but at T240 a quarter note lasts for only a quarter of a
   second.

      Tied notes

   Sometimes music notation ties two or more notes together to make up an
   odd time value or because a note is to be sustained across a measure
   line. In this case, use an ampersand (&) to tie the quantities. For
   example, B4&1&2 is a B played continuously for the length of seven
   quarter notes (tying together a quarter note, a whole note, and a half
   note).

      Trills

   A note will be trilled if you put a tilde (~) before the note letter.
   "Trilling" a note means to alternate it in 32nd notes with the pitch a
   whole step above it. Thus if you code ~C to trill a C, what is
   actually played is rapidly alternating C's and D's.

  Rests (R and P commands)

   Rests are coded with the letter R or P, optionally followed by a
   duration, using the same format as for notes. Just like notes, if a
   rest doesn't have a time value coded, it takes its duration from the
   most recent L command (below).

   Example: Following L4, a syncopated composition might begin P8 A.,
   which is an eighth-note rest followed by a dotted quarter note.

   There's no difference between P and R rests; P is supported for
   historical compatibility with PC-BASIC.

  Octave selection (O, ^, v, >, and < commands)

   The command On sets the octave for the following notes to n until
   another octave command is found. O3 represents the octave that runs
   from middle C to the B above it; O4 is one octave higher. Values of n
   can be 1 to 10 inclusive, though octave 1 can sound rather growly.

   Before the first octave command, the music language assumes you want
   to start in octave 3, which runs upward from middle C.

   The command ^ or > raises the octave; v or V or < drops down an
   octave. You would use these commands in runs of notes, for instance
   FGAB-^CDvB-.

  Key signature (K command)

   Key signatures are in the form K2- for two flats, K3# or K3+ for three
   sharps. Some compositions change key signatures in the middle, and you
   can do that at any time. To change to a key signature of no sharps and
   no flats, use K0.

   Key signatures are the standard major and minor keys of Western music:

        K1# = F#
        K2# = F# C#
        K3# = F# C# G#
        K4# = F# C# G# D#
        K5# = F# C# G# D# A#
        K6# = F# C# G# D# A# E#
        K7# = F# C# G# D# A# E# B#
        K1- = B-
        K2- = B- E-
        K3- = B- E- A-
        K4- = B- E- A- D-
        K5- = B- E- A- D- G-
        K6- = B- E- A- D- G- C-
        K7- = B- E- A- D- G- C- F-

   If you have an oddball key signature, say G# and A#, you can't
   represent it with the K command and you'll have to put accidentals on
   the individual notes.

  Timing (T and L commands)

   These two commands control different aspects of the timing of a piece.
   The T command sets the speed, like a metronome. The L command gives
   the default time value of a note.

      L for duration

   The Ln command gives the default time value, the duration of any note
   or rest where you don't specify a diration number. For instance, use
   L2 if most notes in a piece or section of a piece are half notes; use
   L4. if most are dotted quarter notes. You can use the L command with
   different values, for instance if one section has mostly quarter notes
   and another has mostly eighth notes.

   Before the first L command, or if you don't use an L command, any note
   or rest without a duration of its own will be a quarter.

   The default duration n can be any whole number, not necessarily a
   power of 2. For instance, if you have a run of quarter-note triplets,
   you could code L6.

      T for timing

   You control the overall speed of the piece with the Tn command, where
   n is the number of quarter notes per minute. For instance, if you want
   140 quarter notes per minute (a good march tempo), use T140. You can
   change tempos in a piece as often as you like, by using new T
   commands.

   If you don't specify a tempo, T100 is used.

   Remember that the L and T commands are independent of each other. If
   you type L2T140, that doesn't mean that there are 140 half notes per
   minute. Rather, the L2 means that every note or rest will be a half
   unless you mark it with a duration, and T140 means that there are 140
   quarter notes per minute, which works out to 70 half notes. If you
   have a metronome marking like dotted quarter equals 120, you have to
   do the math and see that that means an ordinary quarter note equals
   80, so you code T80.

  Style and phrasing (M commands)

   Normal playing style has a short space between notes. This might seem
   surprising, but consider even a simple song like

        edcdeee2 ; Mary had a little lamb

   Without short spaces between the notes, the three E's of "little lamb"
   would run together and sound like one long note. In fact, what seems
   most natural is to sound each note for 7/8 of its nominal value
   followed by a break of 1/8 nominal. This is "music normal", coded MN,
   and it is the default.

   There are two alternatives: staccato, MS, which will sound each note
   for 3/4 of its nominal value and break for the remainder; and legato,
   ML, which sounds each note for its full nominal value with no spacing
   between notes. Use MN to reurn to normal playing.

   A special case is an n-note phrase, MPn for "music phrase". If you
   insert MP or MP2 before the first note of a two-note phrase, the two
   notes will be played legato (no spacing) and then play will revert to
   MN (even if it was staccato before). You can specify any reasonable
   number of notes in a phrase, for example MP4.

   Music notation marks tied notes using a curving line similar to a
   phrase. You can code ties notes as several identical notes in a
   phrase, or use the tie marker &; see Duration of notes, above.

   The background and foreground commands from PC-BASIC, MB and MF, are
   ignored. All music is foreground.

  Summary of music commands

   In the following summary, n stands for an unsigned number.

   A to G
          Play the indicated note. The note may be followed by an
          accidental or a duration, or both in that order:

          + Accidentals are # or + (sharp), - (flat), / (natural), X or x
            (double sharp), or _ (underscore, double flat). Naturals are
            needed only to avoid a sharp or flat implied by a key
            signature (K command).
          + Durations are a whole number 1 or greater (default as
            specified in the most recent L command), optionally followed
            by one or two dots to extend the time value by 50% or 75%.
            Durations may also be added by ampersands (&): G8.&1 means a
            single G, played for the combined duration of a dotted eighth
            note and a whole note.

   Kn#, Kn+, Kn-
          Set the key signature to n sharps (# or +) or flats (-). Thus
          K3- means that every subsequent B, E, or A will be flatted
          unless coded with the natural sign (/) or with some other
          accidental. The 15 standard Western key signatures are
          supported, with n from 1 to 7 or K0 (the default) for no
          implicit sharps or flats.

   Ln
          Set the default time value of the following notes to n, where 1
          is a whole note, 4 is a quarter note, 6 is a quarter note in a
          triplet, and so on. The default is L4. Dots are allowed, as L4.
          to make a dotted quarter note the standard time value. The time
          value in this L command will be applied to any folowing notes
          or rests that don't have a duration coded explicitly.

   ML, MN, MS
          Play in legato style, normal style, or staccato style. The
          default is MN.

   MPn
          Music phrase: play the next n-1 notes in legato and the
          following notes in normal (see MN). If n is omitted, the next
          two notes will be played as a phrase. (When you want to tie two
          notes of the same pitch so that they play uninterruptedly, it
          may be easier to use the & notation; see A to G above.)

   On
          Play the following notes in octave n (1 to 10). Each octave
          extends from a C to the B above it. The default octave, O3,
          starts at middle C and contains A440. The O command sets an
          absolute octave; compare the ^ and v commands, which set
          relative octaves.

   Pn or Rn
          Pause (rest) for the indicated duration, or for the duration
          specified in the most recent L command.

   Tn
          Set the speed of play for the following notes so that n quarter
          notes last a minute and other notes last proportionate times.
          Beware of time signatures like 3/2: if you want 70 beats (half
          notes) per minute you must code T140 (140 quarter notes per
          minute). The default is T100.

   V or <
          Play the following notes one octave lower. Compare ^ and O.

   ^ or >
          Play the following notes one octave higher. Compare V and O.

   ~
          Trill the next note: play it in alternation with the note a
          whole step higher, as though the two were written as
          alternating 32nd notes.


   ______________________________________________________________________

                                What's new?
   ______________________________________________________________________

   v1.8, 1999-08-04
          updated contact information (new physical address and URL);
          simplified registration options; added site license pricing

   v1.7, 1999-02-20
          no changes to code or documentation, only updated contact
          information (new ISP)

   v1.6, 1998-11-26
          Package the existing version 1.6 for shareware release: create
          documents without changing the software.

   v1.6, 1994-04-29
          Add the ability to play trills (~).

   v1.5, 1994-04-28
          Add double sharps (X) and double flats (_). Previously, to get
          C-double-flat (for example), you had to translate mentally and
          enter it as B-flat.

   v1.4, 1994-04-27
          Add tied notes (&). Previously, it was necessary to turn on
          legato mode a note early and then turn it off, also a note
          early.

   v1.3, 1994-04-04
          Add ^ and v for rising and falling by an octave. Previously, it
          was necessary to specify the octave number.

   v1.2, 1990-03-04
          If the command line specifies an input file with no extension,
          such as X, first try to read a file called X. Only look for
          X.MUS if X doesn't exist.

   v1.1, 1990-01-14
          Buffer the file input for better performance. Previously, when
          the input file was on a diskette there were noticeable pauses
          every so often.

   v1.0, 1990-01-12
          initial version
