How to add ambient sound to your C or C++ application, using VSS.
Camille Goudeseune
1. Overview
This document explains how to add the simplest
level of sound to your application. It assumes that your application is
written in C or in C++, and that you have a copy of VSS available,
version 3.1 dated 1/1/1999 or later.
The simplest level of sound is a background "ambient" sound environment
which starts when your application starts and ends when your application exits,
with no further interaction.
This document also explains how to simply play back a sound file.
Playing back short sound files triggered by certain events in your
application is popular enough to warrant its inclusion in this introduction.
2. How does VSS work?
-
VSS makes sound on a PC (Windows 95/98/NT or Linux) or SGI.
-
Instead of merely playing back soundfiles, VSS can compute sound in real time.
-
VSS has two parts. The first part, the server, is an application you start up.
Then you start the second part, which is your application. Your application will be a
client of the server, telling VSS to start or stop making sounds.
Your application reads a file ending with the suffix .aud,
which specifies the sounds to be played by VSS. (A .aud file is to a .wav file
what a .html file is to a .gif file, and then some. Read on.)
-
VSS can run on the same machine as your application, or on a different machine
over the network.
2.1 How do I verify that audio is coming out of my computer OK?
If you have an SGI:
- To verify that audio hardware is installed in the computer, type:
hinv -c audio
- Type apanel to display the audio control panel.
- The volume should be up and "mute" should be unchecked.
- In Irix 6.3 and up, the default output device should be "analog out".
- The output sampling rate should be "22.050 kHz".
- Use the audio control panel's "Help" menu if it isn't behaving as described here.
- Type this command, which will play a cheering sound:
sfplay /afs/ncsa/packages/vss/tut/sounds/ski/win.aiff
(If you're not at NCSA, find another aiff file and sfplay it instead.)
If you don't hear anything, check the cables, power switches, and volume
controls between the computer and the loudspeakers.
If you're using Windows:
- Click START, SETTINGS, CONTROL PANEL.
- Double-click on the icon marked SOUNDS.
- In the EVENTS box, you may see a few icons of loudspeakers.
Click on one of them. Then click the triangular (play) button under
PREVIEW.
You should hear a sound like a ding or a chord or a chime or something.
- If you hear nothing, make sure your computer has a working sound card,
and that the software and/or hardware volume controls are turned up.
(Consult your owner's manual, your sysadmin, or Microsoft.)
2.2 Once I know audio is working, how do I verify that VSS is working?
- Change to the directory ambiences.
- Run VSS by typing at a shell prompt
vss &
The control panel for VSS will appear on your screen.
(VSS must still be running during the next three steps.)
- Play a descending flute tone by typing this command:
example flute.aud
- Hit the return key to end the sound.
- Click the QUIT button on VSS's control panel to end VSS.
2.3 How do I run VSS with my application on the same computer?
- Start VSS (as above, by typing "vss").
- Run your application (as many times as you like).
- Click the QUIT button on VSS's control panel to end VSS.
2.4 How do I run VSS with my application on two different computers?
- Start VSS, e.g. on the computer named foo.ncsa.uiuc.edu.
- On the computer for your application, set the environment variable SOUNDSERVER
to foo.ncsa.uiuc.edu. You can do this in csh by typing:
setenv SOUNDSERVER foo.ncsa.uiuc.edu
- Run your application (as many times as you like).
- Click the QUIT button on VSS's control panel to end VSS.
3. How do I add ambient sound to my application?
- In your source file containing the call to main(),
make the following changes.
- Near the beginning of the file, add this line:
#include "/afs/ncsa/packages/vss/6.5/vssClient.h"
(Change "6.5" to "6.3" or "5.3" if you're using that version of Irix;
use another pathname if you're not at NCSA.)
- Before significant graphics has started, add these lines:
BeginSoundServer();
AUDinit("testtone.aud");
- After graphics have ended, add this line:
EndSoundServer();
- In your makefile, add /afs/ncsa/packages/vss/6.5/libsnd.a
to the link command that builds your application. (Again, if you're not
at NCSA, replace /afs/ncsa/packages/vss with where you have VSS.)
You may need a variant of libsnd.a if you're compiling with particular
SGI compilers: libsnd_64.a, libsnd_n32.a, libsnd_o32.a.
If you're writing a Windows application, link with libsnd.lib,
and ensure that your application can find libsnd.dll when it runs
(typically by putting libsnd.dll in the same directory as
your application).
The files vssClient.h and libsnd.a are part of the VSS download.
- If your application is straight C with no C++, also add the option -lC
to the link command that builds your application.
On some machines, -lC fails, or generates mysterious run-time errors. If so, link with CC or g++ instead of cc or gcc or ld.
(The point is to get the C++ runtime libraries which libsnd.a needs.)
- Rebuild your application.
- Copy testtone.aud
to the directory your application runs from.
(If your web browser tries to play a .aud file instead of displaying
it as text, save it to your hard disk instead. Or use the
Lynx text-only browser.)
- Now you can run your application as described above in section 2.
Once you've got the test tone sounding with testtone.aud,
you can use a different sound, say foo.aud, as follows:
- Change
AUDinit("testtone.aud");
to
AUDinit("foo.aud");
- Copy foo.aud to the directory your application runs from.
The directory ambiences
contains several .aud files which you can use in this way.
4. How do I play back a sound file in my application?
(Most of these steps are the same as the previous section.)
- In your source file containing the call to main(),
make the following changes.
- Near the beginning of the file, add this line:
#include "/afs/ncsa/packages/vss/6.5/vssClient.h"
(Change "6.5" to "6.3" or "5.3" if you're using that version of Irix;
use another pathname if you're not at NCSA.)
- Before significant graphics has started, add these lines:
BeginSoundServer();
AUDinit("testtrigger.aud");
- After graphics have ended, add this line:
EndSoundServer();
- New Step: Wherever you want to play a cheering sound,
add this line:
AUDupdateSimple("PlayTheCheer", 0, NULL);
- In your makefile, add /afs/ncsa/packages/vss/6.5/libsnd.a
to the link command that builds your application. (Again, if you're not
at NCSA, change /afs/ncsa/packages/vss to where you have VSS.)
- The files vssClient.h and libsnd.a are part of the VSS download.
- If your application is straight C with no C++, also add the option -lC
to the link command that builds your application.
Or link with CC or g++ instead of cc or gcc or ld.
- Rebuild your application.
- Copy testtrigger.aud and cheer.aiff to the directory your application runs from.
- New Step: Edit your copy of testtrigger.aud with a
text editor (vi, jot) and change the directory name from
/nfs/nlx2/vss/latest/65/vss/doc/dummies/ambiences
to the directory your application runs from.
- Now you can run your application as described above in section 2.
4.1 How do I add my own sounds?
If you have just a single sound, just change the string cheer.aiff in the
file testtrigger.aud to the name of your own soundfile. (And
copy your soundfile to the right directory, like you did with cheer.aiff.)
If you have several sounds, do the following for each sound.
- Duplicate the two lines
PlayTheCheer = Create MessageGroup;
AddMessage PlayTheCheer PlaySample h "cheer.aiff";
- In the duplicate, change cheer.aiff to the name of one of your soundfiles.
- In the duplicate, also change PlayTheCheer to a word of your
own choosing (has to begin with a letter; case-sensitive).
- Whatever you changed PlayTheCheer to, use that in your C
code to cause the sound to play, with the statement
AUDupdateSimple("PlayTheCheer", 0, NULL);
5. Another example: Ski
This is a little scrolling videogame.
It plays a looped background sound continuously,
and also plays triggered sounds when certain things happen (user input and
change of game state). This code should be easy to tweak into your own designs.
Play the game by going to the ambiences/ski directory
and typing vss to start vss from there. (If vss isn't in your path,
type /afs/ncsa/packages/vss/6.5/vss or something like that.)
From another terminal (where you'll play the game), change to
that same directory and type ski. (You might have to type make first to create the file ski.)
Wait for the starting tone to sound, then press the a and
s keys to swish left or right. (Don't hold the keys down.) Press
q to quit in the middle of a run.
The source code in ski.c does all of the things in the checklists
above for playing ambient sounds and playing triggered soundfiles:
- BeginSoundServer()
- AUDinit("ski.aud");
-
AUDupdateSimple("TurnL", 0, NULL);
AUDupdateSimple("TurnR", 0, NULL);
AUDupdateSimple("Crash", 0, NULL);
AUDupdateSimple("Win", 0, NULL);
AUDupdateSimple("Exit", 0, NULL);
- EndSoundServer();
The file ski.aud does several things when it is opened by the AUDinit()
function call:
-
Load the DSO's which contain the actors we'll need;
-
Define a few message groups (TurnL, TurnR, Crash, Win, and Exit);
-
Create and initialize the actors we need (in this case, just a SampleActor);
-
Preload the soundfiles we'll use, so they're in memory immediately;
-
Put instructions into the message groups (typically, just a single message
to play a soundfile);
-
Start playing a background sound;
-
Play a starting sound.
Please refer to the file ski.aud
itself for a detailed explanation.
6. Troubleshooting.
-
VSS can't find my sound files!
A subtlety to remember: .aud files are loaded by your application (client side),
but .aiff files are loaded by VSS itself (server side). Make sure that
the machine running VSS can see the .aiff files. (You can put the .aiff
files anywhere you like; just make sure that the SetDirectory
command in your .aud file points to where you put them.)
(Why doesn't the client load .aiff files itself?
Because it doesn't need them. Sound files are to sound
what texture maps are to graphics. If your application has two components,
one doing heavy computation on a supercluster and another doing graphics
in the CAVE, texture maps go to the CAVE, not to the supercluster.)
-
VSS finds my sound file, but won't load it.
It's got to be an .aiff file, not .au or .wav or .mp3 or even .aifc.
On SGI, the command sfinfo foo.aiff tells you what the
format of a sound file really is (nevermind what its name is).
sfinfo shold say:
File Format: Audio Interchange File Format (aiff) ...
Format: 1 or 2 channel 16-bit integer (2's complement, big endian) file.
(8-bit files work too, though they sound worse. .aifc files sometimes
work, too, but don't count on it.)
To convert a file foo from some other format to .aiff, type:
sfconvert foo foo.aiff format aiff
or, if that doesn't work,
sfconvert foo foo.aiff format aiff int 16 2
(If all of the above looks okay and the file still won't load, try loading and
resaving the file with a sound editor (like SGI's soundeditor).
It may have had an unusual data offset -- some old AIFF files had a
data offset of 62 instead of 124. (SGI's sfinfo command reports
the data offset too.) Arcanities, arcanities.)
-
VSS loads my sound file OK, but it sounds like really loud static.
Probably the sound file got copied at some point from a Windows computer to a Unix
(SGI) computer in such a way that its endianness got reversed (more precisely, between computers with Intel and non-Intel CPUs).
sfinfo should report:
Format: ... (2's complement, big endian), not
Format: ... (2's complement).
If this is the problem, convert the file with sfconvert or sox or some other audio utility.
-
VSS loads my sound file OK, but it sounds growly and very slow.
If it sounds like a 78 RPM record being played at 33 RPM, then there's
probably a mismatch between VSS's "sampling rate" and SGI Audio Panel's
"sampling rate". From a shell prompt, type "apanel", select the output,
and from the menu choose Selected/Sample_Rate/xxx_kHz to match VSS's
sampling rate (probably 22.05 kHz). This can happen in Irix 6.3.
-
My sounds play fine, but they're driving me crazy.
The shorter, the better.
You're going to hear these sound a lot and be able to
recognize them in the first 40 milliseconds, so anything beyond
a second or two may be just
clutter.
[ up to main page ]
Next:
Parambient sound.