OpenAL 1.1 Specification and Reference

The first discussions about implementing OpenAL as an audio API complementary to OpenGL started around 1998. There were a few aborted attempts at creating the headers and a specification, but by late 1999 Loki Entertainment Software was in need for an API of exactly this type and pursued both a specification and a Linux implementation. At around that time, Loki started talking with Creative Labs about standardizing the API and expanding platform support. The OpenAL 1.0 specification was released in early 2000 and compliant OpenAL libraries were released in the same year for Linux, MacOS 8/9, Windows, and BeOS. Loki Entertainment also shipped several games using OpenAL in 2000 - Heavy Gear 2 and Heretic 2 (both under Linux). In 2001, Creative Labs released the first hardware-accelerated OpenAL libraries. The libraries supported the SoundBlaster Live on MacOS 8/9 and Windows.

Since 2001, there has been continuous improvement in OpenAL. Some platforms are less relevant than in 2000 (BeOS and MacOS 8/9 for instance), but more platforms have been added as well (BSD, Solaris, IRIX, Mac OS X, and the popular console gaming platforms). Hardware support is enabled for many Creative and NVIDIA audio devices under Windows as well.

In terms of product support, OpenAL has been used in a large number of titles over the years, on many platforms (for a list of many of the titles, see https://www.openal.org/titles.html).

OpenAL (for "Open Audio Library") is a software interface to audio hardware. The interface consists of a number of functions that allow a programmer to specify the objects and operations in producing high-quality audio output, specifically multichannel output of 3D arrangements of sound sources around a listener.

The OpenAL API is designed to be cross-platform and easy to use. It resembles the OpenGL API in coding style and conventions. OpenAL uses a syntax resembling that of OpenGL where applicable.

OpenAL is foremost a means to generate audio in a simulated three-dimensional space. Consequently, legacy audio concepts such as panning and left/right channels are not directly supported. OpenAL does include extensions compatible with the IA-SIG 3D Level 1 and Level 2 rendering guidelines to handle sound-source directivity and distance-related attenuation and Doppler effects, as well as environmental effects such as reflection, obstruction, transmission, and reverberation.

Like OpenGL, the OpenAL core API has no notion of an explicit rendering context, and operates on an implied current OpenAL Context. Unlike the OpenGL specification the OpenAL specification includes both the core API (the actual OpenAL API) and the 8 operating system bindings of the ALC API (the "Audio Library Context"). Unlike OpenGL’s GLX, WGL and other OS-specific bindings, the ALC API is portable across platforms as well.

OpenAL is concerned with rendering audio into an output buffer and collecting audio data from input buffers. OpenAL’s primary use is assumed to be for spatialized sample- based audio. There is no support for MIDI.

OpenAL has three fundamental primitives or objects: buffers, sources, and a single listener. Each object can be changed independently; the setting of one object does not affect the setting of others. The application can also set modes that affect processing. Modes are set, objects specified, and other OpenAL operations performed by sending commands in the form of function or procedure calls.

Sources store locations, directions, and other attributes of an object in 3D space and have a buffer associated with them for playback. When the program wants to play a sound, it controls execution through a source object. Sources are processed independently from each other.

Buffers store compressed or uncompressed audio data. It is common to initialize a large set of buffers when the program first starts (or at non-critical times during execution — between levels in a game, for instance). Buffers are referred to by sources. Data (audio sample data) is associated with buffers.

There is only one listener (per audio context). The listener attributes are similar to source attributes, but are used to represent where the user is hearing the audio from. All the sources are rendered (mixed and played) relative to the listener.

The OpenAL library primitive (scalar) data types mimic the OpenGL data types, allowing seamless integration with OpenGL code. Guaranteed minimum sizes are stated for OpenGL data types, but the actual choice of C data type is left to the implementation. All implementations on a given binary architecture, however, must use a common definition of these data types.

Any representable floating-point value is legal as input to an OpenAL command that requires floating point data. The result of providing a value that is not a floating point number to such a command is unspecified, but must not lead to OpenAL being interrupted or terminated. In IEEE arithmetic, for example, providing a negative zero or a denormalized number to an OpenAL command yields predictable results, while providing a NaN or infinity yields unspecified results.

Some calculations require division. In such cases (including implied divisions required by vector normalizations), a division by zero produces an unspecified result but must not lead to OpenAL interruption or termination.

OpenAL maintains considerable state. This document enumerates each state variable and describes how each variable can be changed. For purposes of discussion, state variables are categorized somewhat arbitrarily by their function. For example, although we describe operations that OpenAL performs on the implied output buffer, the output buffer is not part of the OpenAL’s state. Certain states of OpenAL objects (e.g. buffer states with respect to queuing) are introduced for discussion purposes, but not exposed through the API.

OpenAL’s commands are functions or procedures. Various groups of commands perform the same operation but differ in how arguments are supplied to them. To conveniently accommodate this variation, we adopt the OpenGL notation for describing commands and their arguments.

OpenAL can be used for a variety of audio playback tasks, and is an excellent complement to OpenGL for real-time rendering. A programmer who is familiar with OpenGL will immediately notice the similarities between the two APIs in that they describe their 3D environments using similar methods.

For an OpenGL/OpenAL program, most of the audio programming will be in two places in the code: initialization of the program, and the rendering loop. An OpenGL/OpenAL program will typically contain a section where the graphics and audio systems are initialized, although it may be spread into multiple functions. For OpenAL, initialization normally consists of creating a context, creating the initial set of buffers, loading the buffers with sample data, creating sources, attaching buffers to sources, setting locations and directions for the listener and sources, and setting the initial values for state global to OpenAL.

Initialization Example:

The audio update within the rendering loop normally consists of telling OpenAL the current locations of the sources and listener, updating the environment settings, and managing buffers.

Processing Loop Example:

OpenAL detects only a subset of those conditions that could be considered errors. This is because in many cases error checking would adversely impact the performance of an error-free program. The command:

is used to obtain error information. Each detectable error is assigned a numeric code. When an error is detected by AL, a flag is set and the error code is recorded. Further errors, if they occur, do not affect this recorded code. When alGetError is called, the code is returned and the flag is cleared, so that a further error will again record its code. If a call to alGetError returns AL_NO_ERROR then there has been no detectable error since the last call to alGetError (or since the AL was initialized). Error codes can be mapped to strings. The alGetString function returns a pointer to a constant (literal) string that is identical to the identifier used for the enumeration value, as defined in the specification.

The table above summarizes the AL errors. When an error flag is set, results of AL operations are undefined only if AL_OUT_OF_MEMORY has occurred. In other cases, the command generating the error is ignored so that it has no effect on AL state or output buffer contents. If the error generating command returns a value, it returns zero. If the generating command modifies values through a pointer argument, no change is made to these values. These error semantics apply only to AL errors, not to system errors such as memory access errors.

Several error generation conditions are implicit in the description of the various AL commands. First, if a command that requires an enumerated value is passed a value that is not one of those specified as allowable for that command, the error AL_INVALID_ENUM results. This is the case even if the argument is a pointer to a symbolic constant if that value is not allowable for the given command. This will occur whether the value is allowable for other functions, or an invalid integer value.

Integer parameters that are used as names for OpenAL objects such as buffers and sources are checked for validity. If an invalid name parameter is specified in an OpenAL command, an AL_INVALID_NAME error will be generated and the command is ignored.

An attempt to set integral or floating point values out of the specified range will result in the error AL_INVALID_VALUE. The specification does not guarantee that the implementation emits AL_INVALID_VALUE if a NaN or infinity value is passed in for a float or double argument (as the specification does not enforce possibly expensive testing of floating point values).

Commands can be invalid. For example, certain commands might not be applicable to a given object. There are also illegal combinations of tokens and values as arguments to a command. OpenAL responds to any such illegal command with an AL_INVALID_OPERATION error.

If memory is exhausted as a side effect of the execution of an AL command, either on system level or by exhausting the allocated resources at AL’s internal disposal, the error AL_OUT_OF_MEMORY may be generated. This can also happen independent of recent commands if OpenAL has to request memory for an internal task and fails to allocate the required memory from the operating system.

Otherwise errors are generated only for conditions that are explicitly described in this specification.

The application can temporarily disable certain AL capabilities on a per-Context basis. This allows the driver implementation to optimize for certain subsets of operations. Enabling and disabling capabilities is handled using a function pair.

The application can also query whether a given capability is currently enabled or not.

If the token used to specify target is not legal, an AL_INVALID_ENUM error will be generated.

OpenAL is an object-oriented API, but it does not expose classes, structs, or other explicit data structures to the application.

The vast majority of OpenAL objects are dynamic, and will be created on application demand. There are also OpenAL objects that do not have to be created, and can not be created, on application demand. Currently, the listener is the only such static object in OpenAL.

Dynamic objects are manipulated using an integer, which in analogy to OpenGL is referred to as the object’s "name”. These are of type unsigned integer (ALuint). Names can be valid beyond the lifetime of the context they were requested if the objects in question can be shared among contexts. No guarantees or assumptions are made in the specification about the precise values or their distribution over the lifetime of the application. As objects might be shared, names are guaranteed to be unique within a class of OpenAL objects, but no guarantees are made across different classes of objects. Objects that are unique (singletons), like the listener, do not require and do not have an integer "name".

OpenAL provides calls to obtain object names. The application requests a number of objects of a given category using alGen{Object}s. The actual values of the names returned are implementation dependent. No guarantees on range or value are made.

Allocation of object names does not imply immediate allocation of resources or creation of objects: the implementation is free to defer this until a given object is actually used in mutator calls. The names are written at the memory location specified by the caller.

Requesting zero names is a legal NOP. OpenAL will respond with an AL_INVALID_VALUE error if the implementation knows that it can not store n names in the given array or if the implementation knows that it can not generate the requested number of objects due to non-memory resource restrictions. OpenAL will respond with an AL_OUT_OF_MEMORY error if it can not allocate the objects due to lack of available memory.

OpenAL releases object names using alDelete{Object}s, implicitly requesting deletion of the objects associated with the names released. If one or more of the specified names is not valid, an AL_INVALID_NAME error will be recorded, and no objects will be deleted.

Once deleted, the names are no longer valid for use with any OpenAL function calls including calls to alDeleteBuffers or alDeleteSources. Any such use will cause an AL_INVALID_NAME error.

The OpenAL implementation is free to defer actual release of resources. Ideally, resources should be released as soon as possible, but no guarantees are made.

A playing source can be deleted - the source will be stopped automatically and then deleted. A buffer which is attached to a source can not be deleted.

OpenAL provides calls to validate the name of an object. The application can verify whether an object name is valid using the alIs{Object} query. It returns AL_TRUE if the name passed to it is a valid object name, and AL_FALSE otherwise. alIs{Object} does not distinguish between invalid and deleted names.

Calls are provided to control the atrributes of OpenAL objects. These depend on the actual properties of a given object category. The precise API for each category is discussed below. An OpenAL command affecting the state of a named object is usually of the form:

{Object} is the name of an OpenAL object - a Buffer or Listener for example.
{n} indicates the number of values to be passed in (if one, the value is omitted)
{if} indicates the type of the value to be passed in, i for integer, f for float.
{v} indicates that a vector of the given type will be passed in.
T is of the type indicated in the {if} and {v} fields.

The objectName parameter specifies the OpenAL object affected by this call. Use of an invalid name will cause an AL_INVALID_NAME error.

The object’s attribute to be affected has to be named as paramName. OpenAL parameters applicable to one category of objects are not necessarily legal for another category of OpenAL objects. Specification of a parameter illegal for a given object will cause an AL_INVALID_OPERATION error.

Not all possible values for a type will be legal for a given objectName and parameterName. Use of an illegal value or a NULL value pointer will cause an AL_INVALID_VALUE error.

Any command that causes an error is a NOP.

In the case of unnamed (unique) objects, the (integer) objectName is omitted, as it is implied by the {Object} part of function name:

Here are some example OpenAL commands using the format rules above:

Calls to query their current attributes are provided for named and for unique OpenAL objects. These depend on the actual properties of a given object category. The performance of such queries is implementation dependent, no performance guarantees are made. The valid values for the parameter paramName are identical to the ones legal for the corresponding attribute setting function.

For unnamed unique Objects, the objectName is omitted as it is implied by the function name:

The definitions of {Object}, {n}, {if}, {v} and T are the same as with the set commands.

Use of an invalid name will cause an AL_INVALID_NAME error. Specification of an illegal parameter type (token) will cause an AL_INVALID_ENUM error. A call with a destination NULL pointer will be quietly ignored. The OpenAL state and destination memory will not be affected or changed by errors.

Attributes affecting the processing of sounds can be set for various OpenAL object categories, or might change as an effect of OpenAL calls. The vast majority of these object properties are specific to a single OpenAL object category, but some are applicable to two or more categories and are listed separately.

The general form in which this document describes parameters is:

By default, OpenAL uses seconds and Hertz as units for time and frequency, respectively. A float or integral value of one for a variable that specifies quantities like duration, latency, delay, or any other parameter measured as time, specifies 1 second. For frequency, the basic unit is 1/second, or Hertz. In other words, sample frequencies and frequency cut-offs or filter parameters specifying frequencies are expressed in units of Hertz.

OpenAL does not define the units of measurement for distances. The application is free to use its own units, for example, meters, inches, or parsecs. OpenAL provides means for simulating the natural attenuation of sound according to distance, and to exaggerate or reduce this effect. However, the resulting effects do not depend on the distance unit used by the application to express source and listener coordinates. OpenAL calculations are scale invariant.

The specification assumes Euclidean calculation of distances, and mandates that if two sources are sorted with respect to the Euclidean metric, the distance calculation used by the implementation has to preserve that order.

Samples usually use the entire dynamic range of the chosen format/encoding, independent of their real world intensity. For example, a jet engine and a clockwork both will have samples with full amplitude. The application will then have to adjust source gain accordingly to account for relative differences.

Source gain is then attenuated by distance. The effective attenuation of a source depends on many factors, among which distance attenuation and source and listener gain are only some of the contributing factors. Even if the source and listener gain exceed 1.0 (amplification beyond the guaranteed dynamic range), distance and other attenuation might ultimately limit the overall gain to a value below 1.0.

OpenAL currently supports three modes of operation with respect to distance attenuation, including one that is similar to the IASIG I3DL2 model. The application can choose one of these models (or chooses to disable distance-dependent attenuation) on a per-context basis.

Legal arguments are AL_NONE, AL_INVERSE_DISTANCE, AL_INVERSE_DISTANCE_CLAMPED, AL_LINEAR_DISTANCE, AL_LINEAR_DISTANCE_CLAMPED, AL_EXPONENT_DISTANCE, and AL_EXPONENT_DISTANCE_CLAMPED. AL_NONE bypasses all distance attenuation calculation for all sources. The implementation is expected to optimize this situation. AL_INVERSE_DISTANCE_CLAMPED is the IASIG I3DL2 model, with AL_REFERENCE_DISTANCE indicating both the reference distance and the distance below which gain will be clamped. AL_INVERSE_DISTANCE is equivalent to the IASIG I3DL2 model with the exception that AL_REFERENCE_DISTANCE does not imply any clamping. The linear models are not physically realistic, but do allow full attenuation of a source beyond a specified distance. The OpenAL implementation is still free to apply any range clamping as necessary. The current distance model chosen can be queried using alGetInteger{v} and AL_DISTANCE_MODEL.

With all the distance models, if the formula can not be evaluated then the source will not be attenuated. For example, if a linear model is being used with AL_REFERENCE_DISTANCE equal to AL_MAX_DISTANCE, then the gain equation will have a divide-by-zero error in it. In this case, there is no attenuation for that source.

The default attenuation model is AL_INVERSE_DISTANCE_CLAMPED.

While amplification and attenuation commute (multiplication of scaling factors), clamping operations do not. The order in which various gain related operations are applied is:

This section introduces basic attributes that can be set both for the listener object and for source objects. The "Signature" for each attribute refers to the type or types which can be used to represent that attribute. For instance, AL_POSITION can be represented with a floating-point vector (fv - alGetSourcefv or alSourcefv) or with three individual floating-point values (3f - alGetSource3f or alSource3f).

The OpenAL listener object and source objects have attributes to describe their position, velocity and orientation in three dimensional space. OpenAL - like OpenGL - uses a right-handed Cartesian coordinate system (RHS), where in a frontal default view X (thumb) points right, Y (index finger) points up, and Z (middle finger) points towards the viewer/camera. To switch from a left handed coordinate system (LHS) to a right handed coordinate systems, flip the sign on the Z coordinate.

AL_VELOCITY is taken into account by the driver to synthesize the Doppler effect perceived by the listener for each source, based on the velocity of both source and listener, and the Doppler related parameters.

The listener object defines various properties that affect processing of the sound for the actual output. The listener is unique for an OpenAL Context, and has no name. By controlling the listener, the application controls the way the user experiences the virtual world, as the listener defines the sampling/pick-up point and orientation, and other parameters that affect the output stream. The destination output device (e.g. speakers, headphones) and the method used to render the 3D positioning (e.g. HRTFs) is implementation and hardware-dependent.

Sources specify attributes like position, velocity, and a buffer with sample data. By controlling a source’s attributes the application can modify and parameterize the static sample data provided by the buffer referenced by the source. Sources define a localized sound, and encapsulate a set of attributes applied to a sound at its origin, i.e. in the very first stage of the processing on the way to the listener. Source related effects have to be applied before listener related effects unless the output is invariant to any collapse or reversal of order. OpenAL also provides additional functions to manipulate and query the execution state of sources: the current playing status of a source (started, stopped, paused), including access to the current sampling position within the associated buffer.

At this time, buffer states are defined for purposes of discussion. The states described in this section are not exposed through the API (can not be queried, or be set directly), and the state description used in the implementation might differ from this.

A buffer is considered to be in one of the following states, with respect to all sources:

The buffer state is dependent on the state of all sources that is has been queued for. A single queue occurrence of a buffer propagates the buffer state (over all sources) from UNUSED to PROCESSED or higher. Sources that are in the AL_STOPPED or AL_INITIAL states still have queue entries that cause buffers to be PROCESSED.

A single queue entry with a single source for which the buffer is not yet PROCESSED propagates the buffer’s queuing state to PENDING.

Buffers that are PROCESSED for a given source can be unqueued from that source’s queue. Buffers that have been unqueued from all sources are UNUSED. Buffers that are UNUSED can be deleted, or changed by alBufferData commands.

OpenAL provides calls to obtain buffer names, to request deletion of a buffer object associated with a valid buffer name, and to validate a buffer name. Calls to control buffer attributes are also provided.

ALC introduces the notion of a Device. A Device can be, depending on the implementation, a hardware device, or a daemon/OS service/actual server. This mechanism also permits different drivers (and hardware) to coexist within the same system, as well as allowing several applications to share system resources for audio, including a single hardware output device. The details are left to the implementation, which has to map the available backends to unique device specifiers.

All operations of the AL core API affect a current AL context. Within the scope of AL, the ALC is implied - it is not visible as a handle or function parameter. Only one AL Context per process can be current at a time. Applications maintaining multiple AL Contexts, whether threaded or not, have to set the current context accordingly. Applications can have multiple threads that share one more or contexts. In other words, AL and ALC are threadsafe.

For efficiency reasons, certain AL objects are shared across ALC contexts. At this time, AL buffers are the only shared objects.

To use an extension, the application will have to obtain function addresses and enumeration values. Before an extension can be used, the application should verify the presence of an extension using alIsExtensionPresent. The application can then retrieve the address (function pointer) of an extension entry point using alGetProcAddress.

Extensions and entry points can be context-specific, and the application can not count on an extension being available unless alIsExtensionPresent returns AL_TRUE. The application also has to maintain pointers on a per-context basis.

Returns AL_TRUE if the given extension is supported for the current context, AL_FALSE otherwise. extName is not case sensitive – the implementation will convert the name to all upper-case internally (and will express extension names in upper-case).

Returns NULL if no entry point with the name funcName can be found. Implementations are free to return NULL if an entry point is present, but not applicable for the current context. However the specification does not guarantee this behavior.

Applications can use alGetProcAddress to obtain core API entry points, not just extensions. This is the recommended way to dynamically load and unload OpenAL DLL’s as sound drivers.

To obtain enumeration values for extensions, the application has to use alGetEnumValue of an extension token. Enumeration values are defined within the OpenAL name space and allocated according to specification of the core API and the extensions, thus they are context-independent.

Returns 0 if the enumeration can not be found, and sets an AL_INVALID_VALUE error condition. The presence of an enum value does not guarantee the applicability of an extension to the current context. A non-zero return indicates merely that the implementation is aware of the existence of this extension.

An OpenAL 1.1 implementation will always support the ALC_EXT_CAPTURE extension. This allows an application written to the OpenAL 1.0 specification to access the capture abilities expressed in section Capture.

An OpenAL 1.1 implementation will always support the AL_EXT_OFFSET extension. This allows an application written to the OpenAL 1.0 specification to access the offset abilities expressed in section Source Attributes.

An OpenAL 1.1 implementation will always support the AL_EXT_LINEAR_DISTANCE extension. This allows an application written to the OpenAL 1.0 specification to access the offset abilities expressed in sections Linear Distance Rolloff Model and Linear Distance Clamped Model.

An OpenAL 1.1 implementation will always support the AL_EXT_EXPONENT_DISTANCE extension. This allows an application written to the OpenAL 1.0 specification to access the offset abilities expressed in sections Exponential Distance Rolloff Model and Exponential Distance Clamped Model.

An OpenAL 1.1 implementation will always support the ALC_ENUMERATION_EXT extension. This extension provides for enumeration of the available OpenAL devices through alcGetString. An alcGetString query of ALC_DEVICE_SPECIFIER with a NULL device passed in will return a list of devices. Each device name will be separated by a single NULL character and the list will be terminated with two NULL characters.