WHISTLE — Play a Tune on Your PC
User Guide for Release 1.9
Program Dated 29 May 2000 / Document Dated 2 Sep 2002
Copyright © 1998–2008 by Stan Brown, Oak Road Systems
Program Dated 29 May 2000 / Document Dated 2 Sep 2002
Copyright © 1998–2008 by Stan Brown, Oak Road Systems
Summary: WHISTLE will play a tune on your PC’s internal speaker, without a sound card.
Contents:
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
DOS 3.1 or higher is required. WHISTLE will also run in a DOS box under Windows 3.x, 95, 98, or ME. 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.
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.
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
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.)
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
You will find several extended examples in the ZIP file: look for files with the extension MUS.
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?)
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.
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.
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).
The basic pitch is a letter A through G, in upper or lower case, optionally followed by 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 frequencies 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 implied 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.
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.
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).
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 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.
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 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.
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.
The Ln command gives the default time value, the duration of
any note or rest where you don’t specify a duration 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.
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.
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 return 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.
- (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).
G8.&1 means a single
G, played for the combined duration of a dotted eighth note and a
whole note.
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.
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
following notes or rests that don’t have a duration coded explicitly.
MN.
O3, starts at middle C and contains A440. The O command
sets an absolute octave; compare the ^ and v commands, which set
relative octaves.
T140 (140 quarter notes per
minute). The default is T100.
WHISTLE is a mature product and is unlikely to be upgraded significantly. The last release, release 1.9 of 20 May 2000, made some modest improvements in prompts and the help message. This user guide was updated on 2 Sep 2002 to integrate stylesheets.
WHISTLE was first released as shareware on 26 Nov 1998, but I had been using it myself since about 1984. A full history is included in the download file.
this page: http://oakroadsystems.com/sharware/whisuser.htm
You might like to look at our other shareware utilities too.