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...