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.

At NCSA, the latest release of VSS is in /afs/ncsa/packages/vss/. Go to the subdirectory corresponding to your operating system (Irix 5.3, 6.2, 6.3+, and Linux Red Hat 5.2+ as of this writing).

If you don't yet have VSS, you can get it here.

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.
  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.3/vssClient.h"
      (Change "6.3" to "6.2" 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.3/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.)
    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).
  3. 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 instead of cc 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.
  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.3/vssClient.h"
      (Change "6.3" to "6.2" 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.3/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. If your application is straight C with no C++, also add the option -lC to the link command that builds your application.
  4. Rebuild your application.
  5. Copy testtrigger.aud and cheer.aiff to the directory your application runs from.
  6. New Step: Edit your copy of testtrigger.aud with a text editor (vi, jot) and change the directory name from /nfs/atlantia/usr2/projects/audio/dev/dummies/ambiences to the directory your application runs from.
  7. 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);

4.2 Troubleshooting.