# Audio drivers

pyglet can use OpenAL, DirectSound or ALSA to play back audio. Only one of these drivers can be used in an application, and this must be selected before the pyglet.media module is loaded. The available drivers depend on your operating system:

> Windows | Mac OS X | Linux
> --- | --- | ---
> OpenAL [11] | OpenAL | OpenAL [11]
> DirectSound |  |
> |  | ALSA

The audio driver can be set through the `audio` key of the pyglet.options dictionary. For example:

    pyglet.options['audio'] = ('openal', 'silent')

This tells pyglet to use the OpenAL driver if it is available, and to ignore all audio output if it is not. The `audio` option can be a list of any of these strings, giving the preference order for each driver:

> String | Audio driver
> --- | ---
> `openal` | OpenAL
> `directsound` | DirectSound
> `alsa` | ALSA
> `silent` | No audio output

You must set the `audio` option before importing pyglet.media. You can alternatively set it through an environment variable; see Environment settings.

The following sections describe the requirements and limitations of each audio driver.

# DirectSound

DirectSound is available only on Windows, and is installed by default on Windows XP and later. pyglet uses only DirectX 7 features. On Windows Vista DirectSound does not support hardware audio mixing or surround sound.

# OpenAL

OpenAL is included with Mac OS X. Windows users can download a generic driver from openal.org, or from their sound device's manufacturer. Linux users can use the reference implementation also provided by Creative. For example, Ubuntu users can `apt-get openal`. ALUT is not required. pyglet makes use of OpenAL 1.1 features if available, but will also work with OpenAL 1.0.

Due to a long-standing bug in the reference implementation of OpenAL, stereo audio is downmixed to mono on Linux. This does not affect Windows or Mac OS X users.

# ALSA

ALSA is the standard Linux audio implementation, and is installed by default with many distributions. Due to limitations in ALSA all audio sources will play back at full volume and without any surround sound positioning.

# Linux Issues

Linux users have the option of choosing between OpenAL and ALSA for audio output. Unfortunately both implementations have severe limitations or implementation bugs that are outside the scope of pyglet's control.

If your application can manage without stereo playback, or needs control over individual audio volumes, you should use the OpenAL driver (assuming your users have it installed).

If your application needs stereo playback, or does not require spatialised sound, consider using the ALSA driver in preference to the OpenAL driver. You can do this with:

    pyglet.options['audio'] = ('alsa', 'openal', 'silent')

[11] | (1, 2) OpenAL is not installed by default on Windows, nor in many Linux distributions. It can be downloaded separately from your audio device manufacturer or openal.org