                                 InfAud v1.3                            
          A Free High-Fidelity Sound Streaming Engine for Informers     
     -------------------------------------------------------------------
                                Requirements:                           
                                                                        
        A Win32 Operating System: Windows 95, 98, ME, NT4+, 2000, XP    
                        At least a 16-bit sound card                    
                                                                        
          A CPU fast enough to decode multiple simultaneous streams     
                  Enough memory to hold the streaming data              
                                                                        
          DirectX recommended, but not required (Direct8+ is best)      
     -------------------------------------------------------------------
     The files "InfAud.exe","InfAudPre.h","InfAudPost.h","example.inf",
         and this file were written by Donnie Russell, October 2002,    
                    and are given to the user as freeware               
                                                                        
         They may be modified and redistributed without restriction,    
                 but please include the above original files            
     -------------------------------------------------------------------
            The files "house.ogg", "forest.ogg", "wolf.ogg", and        
     "snake.ogg" contain music composed and performed by Jesse Ray Lucas
               These files are available in "InfAudMusic.zip"           
     -------------------------------------------------------------------





This is an Inform development package that allows the playing of high
quality music and sound streams through an external sound engine. The
engine receives commands from your Inform game through the use of a
"sound.log" file. The log is constantly monitored by the engine, and
sound commands are acted upon when received.

Of course, the Z-Machine and Glulx/Glk have built-in sound capabilities,
but they are programmed in completely different ways, and currently,
all available interpreters don't support the streaming of mp3 and Ogg
Vorbis files. This system shares a common sound API for both virtual
machines, and allows a wider variety of effects with less programming.
This package was created for those who wish to easily mix, fade-in, and
fade-out music and other sound streams simultaneously. Multiple ambient
sound sources are also possible.

Your game can be compiled to either Z-Machine or Glulx format, using a
pair of header files: "InfAudPre.h" and "InfAudPost.h". There are some
restrictions:

Z-Machine:

You must use a slightly modified interpreter that locks all script output
to the "sound.log" file. DOS Frotz is included, along with the modified
source code. The commands "script on" and "script off" are disabled in
your Inform game because the script functionality is used by the sound
engine.

Glulx:

The Glulxe interpreter need not be modified. The "sound.log" file is
written by normal Glk file commands. Keep in mind that the Win32 Glulxe
interpreter also makes use of DirectSound, like the sound engine. This
may or may not cause conflicts, depending on how your system is configured.

The sound system is provided by the multiplatform FMOD library, version
3.6 for Win32. This library is free, but if your game is to be sold with
it, you must make arrangements to pay a fee to the creators of the library.
Go to their web site at www.fmod.org for more details.
FMOD is Copyright (c) FireLight Technologies Pty, Ltd 1999-2002

The "InfAud.exe" executable was compiled by the excellent, free compiler
MinGW, available at www.mingw.org.

The "InfAud.exe" program acts as a launcher to your interpreter and
game file. It runs unobtrusively in your system tray. Left-clicking on the
radio icon toggles the main window of the program on and off. When visible,
you can close InfAud by clicking on the close button at the upper-right
corner.





To try out the system, do the following:

Unzip the "InfAud13.zip" package to any location on your hard drive,
keeping the directory structure intact.

Make sure to download the "InfAudMusic.zip" archive and unzip it into
the "InfAud" directory if you want to hear any music in the example
game.

Download the following packages from the IF Archive at www.ifarchive.org
(newer packages than those listed below should be fine, just pay
attention to the directory structure):

libg610.tar.Z             --- uncompress and untar into "InfAud\include";
                              (library files will be in "libg610";
                              please move them up into the parent directory)
infglk-0.6.1.zip          --- unzip into "InfAud\include" directory
inform621_037BP_win32.zip --- unzip into "InfAud\bin\Inform" directory
WinGlulxe-035.zip         --- unzip into "InfAud\bin\Glulxe" directory





Then go to a DOS prompt in Windows, and "cd" to the base directory
"InfAud". Run the batch files "MZ.BAT" and "MG.BAT" to compile the
Z-Machine and Glulx versions of the example game, respectively.

The batch files "EZ.BAT" and "EG.BAT" in the base directory
of the package are set up to launch the Z-Machine and Glulx versions
of the example game.

You can also double-click the batch files from Windows Explorer.

Inside your game interpreter, typing "volume x", where x is a number
between 0 (mute) and 255 (maximum), will set the master volume of all
sounds.

While playing your game in the running interpreter, be careful not to
close the interpreter by clicking on the upper-right close button. It is
best to end your game by typing "quit", then answering "yes". The
engine program will automatically close. If you forget, and the engine
keeps running, left-click on the radio icon to display the InfAud window
and click the close button, or just press the "Esc" key.

The beginning of your Inform game source code (Z-Machine or Glulx)
should look something like this:

          Constant Story "My Inform Game";
          Constant Headline "^featuring a full musical score and sound effects^";

          Include "InfAudPre";
          Include "Parser";
          Include "VerbLib";
          Include "InfAudPost";

Commands similar to the following examples can be issued anywhere afterwards
in your Inform source code. Media files (mp3, wav, etc.) must be present in a
"media/" subdirectory below the current directory, by default. This can be
changed by specifying a new directory as a third parameter to "InfAud.exe",
such as "/MySoundFiles/". The directory must end with a forward slash. The
sound commands in your Inform source code may specify directories below the
"media/" directory as shown below.





------------------------------------------------------------------------------
SOUND("loop loops/forestmusicloop.mp3 +30 128");

This command starts and loops "forestmusicloop.mp3" until it is stopped by
another command.

The fade-in goes from mute to half-volume (128) in 30 tenths of a second (3
seconds).

The "+" sign is not necessary for a fade-in.
------------------------------------------------------------------------------
SOUND("playing loops/forestmusicloop.mp3 -30 close * loop loops/hostilemusicloop.mp3 +30 255");

This is an example of a crossfade.

Commands may be separated by a "*".

The first command fades-out all playing "forestmusicloop.mp3" sounds from their
current volumes and closes their streams in 30 tenths of a second (3 seconds).

The "close" parameter can also be specified by a "-1".

If "close" were replaced by a "0", the stream would play at muted volume.

You must remember to close streams when you fade them down. If too many are
running at the same time, old ones might be affected.

If several identical media files are playing, they are all affected by the
"playing" command.

The second command starts and loops "hostilemusicloop.mp3" until it is
stopped by another command.

The sound will fade-in from quiet to full volume (255) in 30 tenths of a
second (3 seconds).
------------------------------------------------------------------------------
SOUND("playing all -0 close");

This command fades-out and closes all streams instantaneously (in 0 tenths of
a second).

The "-" on the zero is important. It always indicates a fade-out.

The parameter "close" could be replaced by a volume level from 0-255.

Streams generated by an ambient source are also closed, but the ambient
source will still be on, producing new streams.
------------------------------------------------------------------------------
SOUND("play wolfhowl.mp3 +0 255 2");

This will start a "wolfhowl.mp3" and play it 2 times in succession.

The fade-in is instantaneous (in 0 tenths of a second) at full volume (255).

The final number is optional and always assumed to be "1" if missing.

A long fade-in would extend in a continuous linear sweep over all repeated
plays of the sound.
------------------------------------------------------------------------------
SOUND("ambienton ambient/forestcricket.mp3 +5 128 6");

With this command, you can create an ambient source.

An infinite (until stopped) series of "forestcricket.mp3" sounds will play
at a probability of 6 coin-tosses turning up heads consecutively every
50 milliseconds.

Each sound will fade-in within 5 tenths of a second (half a second) from
mute to half volume (128).

Each sound will also be randomly panned (somewhere from left to right).
------------------------------------------------------------------------------
SOUND("ambientoff ambient/forestcricket.mp3");

This will turn off all "forestcricket.mp3" ambient sources.

Streams generated by the source will finish without being affected, but can
be faded and/or closed with a "playing" command.
------------------------------------------------------------------------------
SOUND("ambientoff all");

This will turn off all ambient sources.

Streams generated by the sources will finish without being affected, but can
be faded and/or closed with a "playing" command.
------------------------------------------------------------------------------
SOUND("volume 255");

This command sets the master volume to the maximum level (255).

The range for all volumes is 0-255.
------------------------------------------------------------------------------
SOUND("pan center");

Pan determines the direction a sound comes from.

This command sets the pan direction of all following "play" or "loop"
commands to the center.

Pan can be expressed by "left" (0), "center" (128), "right" (255),
or "off" (-1).

When pan is "off", stereo sounds play at full volume, as opposed to
half-volume when pan is set to "center".

To make a sound play from a 45 degree angle to the left, use:

SOUND("pan 64 * play wolfhowl.mp3 +0 255 * pan off");

Always remember to turn pan "off" so later sounds are unaffected.
------------------------------------------------------------------------------
SOUND("repeatat 10000 * play song.mp3 +10 128 999999999 * repeatat 0");
 
The "repeatat" command affects all following "play" commands.

On the first play, it has no effect. On all following repeated plays,
it sets the position in the file to 10000 milliseconds (10 seconds).

Setting the count to 999999999 simulates an infinite loop.

After your "play" command, you should set "repeatat" back to 0 to be
safe.
------------------------------------------------------------------------------





Command Line Parameters to "InfAud.exe"

1: Path to your interpreter
2: Path to your game file
3: Your media directory (optional, default is "media/")

The path to "InfAud.exe" must contain all backward slashes ("\").
All parameter paths must contain all forward slashes ("/")
This is confusing, I know. Blame Bill.

Examples:

bin\InfAud\InfAud.exe   bin/Glulxe/Glulxe.exe   code/example.ulx   media/
bin\InfAud\InfAud.exe   bin/Frotz/frotz.exe     code/example.z5    media/





Credits:

This project would not have been possible without the help of
Jesse Ray Lucas, who suggested the idea at XYZZYnews
(http://www.xyzzynews.com/), helped with the design, did beta
testing, and last but not least composed and performed all the
music contained in the "InfAudMusic.zip" file.

You can contact him at the following addresses:

email:  jlucas@neoprimitive.net
www:    http://www.neoprimitive.net

All the dedicated people responsible for maintaining the MinGW
port of GCC.

The FMOD music library team.





Final Note:

InfAud is not in any way dependent on the Inform language or any
interpreter. Any computer program that can append text (separated
and/or terminated by the '*' character) to a "sound.log" text file
in the current directory can interface with the program. Try writing
an mp3-player as an MS-DOS batch file, it's not that difficult...
