OpenAL (3D Sound)

OpenAL is a cool cross-platform library for 3D sound. All the sound played by our engine goes through it.

Contents:

1. Developers API

For developers, the decription how to use 3D sound in Castle Game Engine is in manual about sound.

2. Installing OpenAL

Generally, you can install OpenAL from many sources, you can even get optimized OpenAL drivers from your sound card manufacturer. Section below describes how to install OpenAL in the simplest and most often case.

Linux users:

Install appropriate package for your Linux distribution. Look for a package named like libopenal*.

My games work with both common OpenAL implementations: OpenAL Sample Implementation (the original implementation, from Loki, unmaintained) and OpenAL Soft (the newer, maintained version). Modern distributions (at least Debian and Ubuntu) contain OpenAL Soft.

FreeBSD users:

Simple pkg_add -r openal command should do the trick.

Mac OS X users:

New Mac OS X installs have OpenAL already installed. If not, you can download and run Creative free OpenAL installer for Mac OS X. (Choose OpenAL_Installer_OSX, that is OpenAL Installer for MacOS X.)

Windows users:

OpenAL libraries (DLL files) should already be included in all binary packages of my games under Windows. So you don't have to do anything.

However, you're free to remove appropriate DLL files (OpenAL32.dll and wrap_oal.dll) provided in my archives and install OpenAL yourself. This is especially handy if you want to use other OpenAL implementation than the one from Creative. OpenAL libraries that are provided by default come from Creative free OpenAL installer (choose oalinst, that is OpenAL Installer for Windows).

You can always compile from sources. See OpenAL Soft or Creative source code instructions.

3. Command-line options respected by all my programs that use OpenAL

--no-sound

Don't output any sound, even if OpenAL is available and seems perfectly working. Our programs will not even try to initialize OpenAL in this case. Note that you don't have to use this option if you don't have OpenAL installed. This parameter is useful only if you have OpenAL, but you don't want to use it for whatever reason (e.g. because your cat sleeps on the chair beside you and you don't want to wake him up).

--audio-device DEVICE-NAME

Use given DEVICE-NAME for sound output. Usually, the default one should be the best.

To list the available devices use the --help command-line option (at the --audio-device description you will see a list of devices detected). In The Castle you can also see and choose them by the Sound output device menu. In view3dscene you have comfortable menu File -> Preferences -> Sound Device.

Windows users:

You may see two devices with newer OpenAL implementation: "Generic Hardware" (uses DirectSound3D) and "Generic Software" (uses DirectSound). As far as I know, "Generic Software" can only support stereo sound (2 channels, not more). On the other hand, it sometimes sounds better than "Generic Hardware".

So be sure to try both devices and choose the better one.

Linux and FreeBSD users with OpenAL-Soft (newer) implementation:

The default device selected on Linux should usually be ALSA, and should work perfectly on modern systems.

A useful device is "Wave File Writer", to record 3D sound to file. Note that you have to specify output filename in config file, otherwise it will not work. For example, make a file $HOME/.alsoftrc with two lines:

[wave]
file = /tmp/output.wav

For more configuration options, look into /etc/openal/alsoft.conf that should be installed with openal-soft package. It contains many comments about the possible options.

Linux and FreeBSD users with OpenAL Sample (older) implementation:

The following devices are available:

OpenAL Name	Device	Notes
native	operating system native	The default device.
sdl	Simple DirectMedia Layer backend
arts	aRTs backend	Note that it seems terribly unstable. Use at your own risk.
esd	Esound daemon backend
alsa	ALSA backend	While it works OK, it tries to acquire the exclusive ownership over sound device. So, unlike most other programs that use ALSA, OpenAL programs by default cannot play sound when some other program already plays sound. For example, you cannot run rhyrthmbox and listen to your own chosen music while playing my games. The workaround is to run my games through aoss wrapper.
waveout	WAVE file output	A file named like openal-0.wav will be generated that contains recorded sound. Note that OpenAL generates somewhat buggy WAV file, and e.g. gstreamer-based programs may not want to play it. My programs will play it, but only because I made a workaround specifically for this. I found that it's usually a good workaround to convert the WAV file with sox, like sox openal-0.wav newopenal-0.wav. Such WAV file generated by sox should be readable everywhere. I reported this problem to Debian OpenAL package (probably a problem is general and fix will be generally usable too) here.
null	no output

In the simplest case, to use some other device, e.g. alsa, just run program with command-line option like:

  --audio-device "'(( devices '(alsa) ))"

(Yes, the first argument's character is an apostrophe, and the whole argument is quoted to avoid being splitted by shell. No, it's not Lisp, but it was designed to look similar.)

Then if you will find that e.g. alsa device sounds best and you want my programs (and all other programs that use OpenAL) to always use alsa device, you can create file /etc/openalrc or $HOME/.openalrc with line

  ( define devices '(alsa) )