(This is the user guide in plain text. If you have any Web browser,
you may prefer to read WHISUSER.HTM, which has all the same text but
is better formatted and contains many helpful hyperlinks.)



                     WHISTLE -- Play a Tune on your PC
                           User Guide and History

         program and documentation by Stan Brown, Oak Road Systems
                            revised 30 May 2000
           Copyright  1998-2000 by Stan Brown, Oak Road Systems
  ------------------------------------------------------------------------

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

         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 3.x, 95, or 98. I haven't tested it under Windows NT/2000, but a
friend ran a quick test and said it worked for him in NT 4.0.

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

                            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 may 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:
        o 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).
        o 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.9, 2000-05-30
     modest improvements in prompts and help message; fix a broken link in
     the user guide
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
