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?

2.1 How do I verify that audio is coming out of my computer OK?

If you have an SGI:
  1. To verify that audio hardware is installed in the computer, type:
    hinv -c audio
  2. Type apanel to display the audio control panel.
    1. The volume should be up and "mute" should be unchecked.
    2. In Irix 6.3 and up, the default output device should be "analog out".
    3. The output sampling rate should be "22.050 kHz".
    4. Use the audio control panel's "Help" menu if it isn't behaving as described here.
  3. 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:
  1. Click START, SETTINGS, CONTROL PANEL.
  2. Double-click on the icon marked SOUNDS.
  3. 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.
  4. 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?

  1. Change to the directory ambiences.
  2. 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.)
  3. Play a descending flute tone by typing this command:
    example flute.aud
  4. Hit the return key to end the sound.
  5. 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?

  1. Start VSS (as above, by typing "vss").
  2. Run your application (as many times as you like).
  3. 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?

  1. Start VSS, e.g. on the computer named foo.ncsa.uiuc.edu.
  2. 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
  3. Run your application (as many times as you like).
  4. Click the QUIT button on VSS's control panel to end VSS.

3. How do I add ambient sound to my application?

  1. In your source file containing the call to main(), make the following changes.
    1. 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.)
    2. Before significant graphics has started, add these lines:
      BeginSoundServer();
      AUDinit("testtone.aud");
    3. After graphics have ended, add this line:
      EndSoundServer();
  2. 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.

  3. 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.)
  4. Rebuild your application.
  5. 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.)
  6. 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:
  1. Change
    AUDinit("testtone.aud");
    to
    AUDinit("foo.aud");
  2. 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.)
  1. In your source file containing the call to main(), make the following changes.
    1. 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.)
    2. Before significant graphics has started, add these lines:
      BeginSoundServer(); AUDinit("testtrigger.aud");
    3. After graphics have ended, add this line:
      EndSoundServer();
    4. New Step: Wherever you want to play a cheering sound, add this line:
      AUDupdateSimple("PlayTheCheer", 0, NULL);
  2. 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.)
  3. The files vssClient.h and libsnd.a are part of the VSS download.
  4. 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.
  5. Rebuild your application.
  6. Copy testtrigger.aud and cheer.aiff to the directory your application runs from.
  7. 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.
  8. 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.
  1. Duplicate the two lines
    PlayTheCheer = Create MessageGroup;
    AddMessage PlayTheCheer PlaySample h "cheer.aiff";
  2. In the duplicate, change cheer.aiff to the name of one of your soundfiles.
  3. In the duplicate, also change PlayTheCheer to a word of your own choosing (has to begin with a letter; case-sensitive).
  4. 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:

The file ski.aud does several things when it is opened by the AUDinit() function call:

  1. Load the DSO's which contain the actors we'll need;
  2. Define a few message groups (TurnL, TurnR, Crash, Win, and Exit);
  3. Create and initialize the actors we need (in this case, just a SampleActor);
  4. Preload the soundfiles we'll use, so they're in memory immediately;
  5. Put instructions into the message groups (typically, just a single message to play a soundfile);
  6. Start playing a background sound;
  7. Play a starting sound.
Please refer to the file ski.aud itself for a detailed explanation.

6. Troubleshooting.


[ up to main page ]

Next: Parambient sound.