(* BackPlay -- A unit for playing music in the background.

Version 1.00 -- 9/24/1988 -- First version

Copyright 1988 Scott Bussinger
All rights reserved.

Scott Bussinger
Professional Practice Systems
110 South 131st Street
Tacoma, WA 98444
(206)531-8944
Compuserve [72247,2671]

This unit allows you to play music in the background of your Turbo Pascal 5.0
programs. In the background means that once you start the music playing, you
can continue on with the rest of your program and the music keeps playing
without any additional effort on your part until the song is finished. You can
use this to provide special sound effects in your programs or just to add a
cute indication that your program is still working on something.
The unit accepts music files from Neil Rubenking's PianoMan program version
4.0 and the code in this file is based on information gained from his sample
music playing routines. You can either play the .MUZ files off of your disks,
or imbed the the MUZ data directly into your program so the the file need not
be available at run time. Neil's PianoMan is an excellent shareware product
and is available from many bulletin boards on in the IBM Software forum on
Compuserve. It allows you to play your computer's keyboard like a piano
keyboard and record and edit music entered in real time or from sheet music.
There are also many files of songs already entered that you can use. One sample
archive for instance contains over 50 sample songs.

function PlayingInBackground: boolean;
This returns true if there is still music being played in the
background. You may use this to wait for a song to finish before
proceeding.

procedure PlayingMode(Action: SongAction);
This routine lets you change the current way songs are being played.
The acceptable parameters are RepeatSong to cause the current music
buffer to be repeated endlessly when the song finishes. This mode
continues until EndRepeatSong or StopSong is used, the program ends
or you call PlayMuz or PlaySong again. SuspendSong turns off the
music temporarily (perhaps to ask the user a question) and the music
will continue when ResumeSong is used. StopSong will end the current
song immediately.

function PlayMuz(Filename: string): boolean;
This routine loads an MUZ file from disk and adds it to the current
music buffer. If a song is currently playing, it will start when the
current song ends otherwise the song will start immediately. This
routine automatically clears the RepeatSong mode. PlayMuz returns
true if the file was found or false if not found. It will look for
the .MUZ file first in the current directory and then in all of the
directories in the current PATH.

procedure PlaySong(S: Song);
This routine is like PlayMuz, except it plays a song that is imbedded
into your program using the {$L} compiler directive. To load an
.MUZ file use the BINOBJ program that comes with Turbo Pascal to
convert the .MUZ file to an .OBJ file with a line like:
BINOBJ HITCHKOK.MUZ HITCHKOK Hitchkok
and include it in your program as an external routine like:
{$L HITCHKOK.OBJ}
procedure Hitchkok; external;
to play this song, you'll use PlaySong(Hitchkok). This lets you play
songs without including a lot of extra files with your program.

Note that there is a size limit to the background music buffer. This is set
by constant BackgroundBufferSize and is normally 256 note changes. A staccato
is treated as two notes (the 'on' part and the rest between notes) so this will
handle up to about 128 notes in a typical song. The buffer is only cleared
when the entire buffer is emptied (and silence prevails), so if you keep
calling PlayMuz or PlaySong and the previous song isn't over, the buffer just
gets larger. The music is automatically turned off when the program ends.
There's one last limitation on the techniques used by BackPlay. Note changes
can only take place 18.2 times a second (the standard system clock rate). All
note durations and staccatos in the song are rounded to the nearest number of
clock ticks. This means that the song may have a slightly different tempo when
played using BackPlay than it does under PianoMan and that very short notes and
staccatos may disappear altogether. Most of the multivoice songs done in
PianoMan will sound terrible with BackPlay because of this limitation.
If you compile this file you'll see an example program this uses both
PlaySong and PlayMuz. The first part shows that the music continues while
calculations take place. The last part show how you can wait for a song to
finish before continuing (or ending the program in this case). Before compiling
the demo, you'll need to convert the PLAYDEM1.MUZ file into PLAYDEM1.OBJ using
the BINOBJ utility that comes with Turbo Pascal using the following command
line at a DOS prompt:
BINOBJ PLAYDEM1.MUZ PLAYDEM1 PlayDem1
*)

program PlayDemo;

uses BackPlay;

var I: longint;

{$L PLAYDEM1.OBJ}
{$F+}
procedure PlayDem1; external;
{$F-}

begin
PlaySong(PlayDem1); { Start playing the first song (already in memory) }
for I := 1 to 250 do { Look busy }
writeln(I:3,sqr(I):10);
if not PlayMuz('PLAYDEM2') then { Play second song (loaded from disk file PLAYDEM2.MUZ }
writeln('PLAYDEM2.MUZ not found.');
while PlayingInBackground do ; { Wait for song to finish }
end.