pygame2.openal – basic OpenAL wrapper module

Todo

detailled description of the OpenAL model, including contexts, devices, source and listener bindings and the context/state driven behaviour.

Type identifiers for the property get and set methods:

‘b’ Get or set a single boolean value (e.g. AL_TRUE)
‘ba’ Get or set an array of boolean values. The array can be any type of sequence containing matching values.
‘i’ Get or set a single integer value.
‘i3’ Get or set an triplet of integer values. The array can be any type of sequence containing matching values.
‘ia’ Get or set an array of integer values. The array can be any type of sequence containing matching values.
‘f’ Get or set a single floating point value.
‘f3’ Get or set an triplet of floating point values. The array can be any type of sequence containing matching values.
‘fa’ Get or set an array of floating point values. The array can be any type of sequence containing matching values.
‘d’ Get or set a single double precision floating point value.
‘da’ Get or set an array of double precision floating point values. The array can be any type of sequence containing matching values.

Module Functions

pygame2.openal.al_get_string(prop) → str

Retrieves an OpenAL string property.

For valid property values, see pygame2.openal.constants.

Example:

import pygame2.openal as openal
import pygame2.openal.constants as const

print (openal.al_get_string (const.AL_VENDOR))
pygame2.openal.get_default_capture_device_name() → str
Gets the name of the default capture device.
pygame2.openal.get_default_output_device_name() → str
Gets the name of the default output device.
pygame2.openal.get_enum_value(name) → long
Gets the value of an OpenAL enumeration name.
pygame2.openal.get_error() → str

Gets the last OpenAL error message occured.

OpenAL maintains an internal error message. This message will usually be given to you when a pygame2.Error is raised.

You will rarely need to call this function.

Note

Once called, the internal OpenAL error message will be cleared, so that subsequent calls of this function will return None, until a new OpenAL error occurs.

pygame2.openal.init()

Initializes the underlying OpenAL library.

Note

This function is currently only available for compliance with other pygame2 modules, but does not actually perform anything. The behaviour might change in later pygame2 versions, so it is generally safe to call this function.

pygame2.openal.is_extension_present(name[, device]) → bool

Checks, whether the specified extension is available.

Checks, whether the extension specified by name is available in the current OpenAL implementation. If a device is passed, the OpenAL’s :pygame2.openal.Device` will be checked for the extension.

pygame2.openal.list_capture_devices() → [str, str, ...]

Retrieves a list of available capture devices.

Retrieves a list of available and supported capture device names. If no capture devices could be found, an empty list is returned.

pygame2.openal.list_output_devices()

Retrieves a list of available output devices.

Retrieves a list of available and supported output device names. If no output devices could be found, an empty list is returned.

pygame2.openal.quit()

Shuts down the underlying OpenAL library.

Note

This function is currently only available for compliance with other pygame2 modules, but does not actually perform anything. The behaviour might change in later pygame2 versions, so it is generally safe to call this function.

pygame2.openal.set_current_context(context) → bool

Switches the current OpenAL context.

Switches the current OpenAL context. The current OpenAL context can then be influenced in various ways, such as attaching sources, buffers and tweaking its settings.

Returns True, if the context could be switched successfully, otherwise False.

Buffers

class pygame2.openal.Buffers → NotImplementedError

Buffers objects are used by OpenAL to buffer and provide PCM data for playback, recording and manipulation.

The Buffers object provides methods and properties to manipulate certain aspects of the buffered data and can be queued to multiple Sources within the same context.

Buffers instances cannot be created directly, but are bound to a Device. To create a Buffers instance for the currently active Device, use the Context.create_buffers() method on the currently active Context.

Attributes

Buffers.buffers
Gets the buffer identifiers used in the Buffers instance.
Buffers.count
Gets the number of buffers managed in the Buffers instance.

Methods

Buffers.buffer_data(bufnum, format, data, samplerate) → None

Buffers a chunk of data into one of the created buffers.

Buffers a chunk of PCM data into the buffer at bufnum. format describes the audio format of the data (see pygame2.openal.constants for more details). samplerate denotes the sample rate in Hz.

Buffers.get_prop(bufnum, prop, type) -> value or (value, ...)

Retrieves the value(s) of an OpenAL property for the Buffers.

Retrieves the value or values of a buffer-related OpenAL property for the buffer identified by bufnum. prop can be any valid buffer constant and type must be a valid value type identifier for the constant.

Buffers.set_prop(bufnum, prop, value[, type]) → None

Sets the value(s) of an OpenAL property for the Buffers.

Sets the value or values of a buffer-related OpenAL property for the buffer identified by bufnum. prop can be any valid buffer constant, while value must be valid for the constant.

If type is omitted, the function tries to guess, which type should be used from the passed value(s). Guessing tries to convert values implicitly, where possible, so if there are ambiguous values, it is better to provide type.

CaptureDevice

class pygame2.openal.CaptureDevice(frequency, format, bufsize) → CaptureDevice
class pygame2.openal.CaptureDevice(name, frequency, format, bufsize) → CaptureDevice

Creates a sound capturing device.

The CaptureDevice acts as recorder for a certain hardware device and allows the caller to record incoming sound samples (e.g. from a microphone or line-in device).

The captured samples will be stored in an internal buffer, which is guaranteed to hold bufsize samples. Depending on the passed format and frequency, captured samples can vary in their byte size (see pygame2.openal.constants for more details) and speed of occurance.

Attributes

CaptureDevice.format
Gets the set audio format for the CaptureDevice.
CaptureDevice.frequency
Gets the set frequency in Hz for the CaptureDevice.
CaptureDevice.size
Gets the default buffer size for the CaptureDevice.

Methods

CaptureDevice.get_samples([buffer]) → (str or bytes) or int

Retrieves the available samples from the CaptureDevice.

Retrieves the samples that are available on the CaptureDevice. If a buffer is provided, the samples will be directly written to the buffer and the amount of bytes written will be returned.

If no buffer is provided, the retrieved samples will be returned as byte sequence (byte string or string).

CaptureDevice.start() → None

Starts capturing incoming samples on the device.

Starts capturing incoming samples for the CaptureDevice. The samples will be stored in the CaptureDevice’s internal buffer. If the buffer is full, the oldest samples will be overwritten with the newest samples (ring buffer).

CaptureDevice.stop() → None
Stops capturing incoming samples.

Context

class pygame2.openal.Context(device[, attribtes]) → Context

Creates a new Context for a specific Device.

OpenAL contexts represent logical state groups, where Sources and a Listener are managed and audio data is correctly streamed to the underlying output Device.

Contexts can be created for multiple devices and independently managed without influencing each other. To be processed correctly at a certain time, a Context must be set as the current one in OpenAL. This will cause OpenAL to process only data from that Context to and from the audio hardware.

Most methods and properties will fail for a Context that is not marked as the current one. So before accessing any member of a Context, make sure, you marked it as current.

Attributes

Context.device
Gets the Device the Context is using.
Context.distance_model
Gets or sets the distance model setting for the Context.
Context.doppler_factor
Gets or sets the doppler factor setting for the Context.
Context.is_current
Gets, whether the Context is marked the current one to process.
Context.listener
Gets the Listener for the Context.
Context.speed_of_sound
Gets or sets the value of the speed of sound for the Context.

Methods

Context.create_buffers(amount) → Buffers
Creates a Buffers instance with amount buffers for the Context.
Context.create_sources(amount) → Sources
Creates a Sources instance with amount sources for the Context.
Context.disable(value) → None
Disables a certain context-specific setting.
Context.enable(value) → None
Enables a certain context-specific setting.
Context.is_enabled(value) → bool
Checks, whether a certain setting is enabled.
Context.make_current() → bool

Tries to mark the Context as current.

Tries to mark the Context as the current one. If the Context could not be marked sucessfully, False will be returned, otherwise True.

Any other Context, which was previously marked as current, will loose this state.

Context.process() → None

Processes the Context.

Processes the Context, causing it to update any internal states, stream audio data to and from the hardware, update the internal source and listener positions and so forth.

Context.suspend() → None
Suspends the Context from processing any data.

Device

class pygame2.openal.Device([name]) → Device

Creates a sound output device.

The Device class acts as sound streaming sink, by default for playing audio data (The CaptureDevice also inherits from Device, but acts as recorder).

Attributes

Device.extensions
Gets a list of available extensions for the Device and OpenAL implementation.
Device.name
Gets the name of the Device as reported by OpenAL.

Methods

Device.get_enum_value(name) → long
Gets the value of a Device-specific OpenAL enumeration name.
Device.get_error() → str

Gets the last OpenAL error message occured on the Device.

OpenAL devices maintain an internal error message. This message will usually be given to you when a pygame2.Error is raised.

You will rarely need to call this function.

Note

Once called, the internal error message will be cleared, so that subsequent calls of this function will return None, until a new error occurs.

Device.has_extension(extname) → bool
Checks, whether a certain extension is available on the Device.

Listener

class pygame2.openal.Listener → NotImplementedError

The Listener represents the user hearing the sounds played by OpenAL in a specific Context. Source playback is done relative to the position of the Listener in the 3D space.

Listener instances cannot be created directly, but are bound to a Context. To create (or get) a Listener instance for the currently active Context, use the Context.listener property.

Methods

Listener.get_prop(prop, type) -> value or (value, ...)

Retrieves the value(s) of an OpenAL property for the Listener.

Retrieves the value or values of a listener-related OpenAL property. prop can be any valid listener constant and type must be a valid value type identifier for the constant.

Listener.set_prop(prop, value[, type]) → None

Sets the value(s) of an OpenAL property for the Listener.

Sets the value or values of a listener-related OpenAL property. prop can be any valid listener constant, while value must be valid for the constant.

If type is omitted, the function tries to guess, which type should be used from the passed value(s). Guessing tries to convert values implicitly, where possible, so if there are ambiguous values, it is better to provide type.

Sources

class pygame2.openal.Sources → NotImplementedError

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.

Sources instances cannot be created directly, but are bound to a Context. To create a Sources instance for the currently active Context, use the Context.create_sources() method.

Attributes

Sources.count
Gets the number of sources managed in the Sources instance.
Sources.sources
Gets the source identifiers used in the Sources instance.

Methods

Sources.get_prop(sourcenum, prop, type) -> value or (value, ...)

Retrieves the value(s) of an OpenAL property for the Sources.

Retrieves the value or values of a sources-related OpenAL property for the source identified by sourcenum. prop can be any valid source constant and type must be a valid value type identifier for the constant.

Sources.pause(sourcenum) → None
Sources.pause((sourcenum1, sourcenum2, ...)) → None

Pauses a single source or a set of sources.

Pauses a single source identified by sourcenum or a set of sources identified by the passed sequence of source identifiers.

Sources.play(sourcenum) → None
Sources.play((sourcenum1, sourcenum2, ...)) → None

Plays a single source or a set of sources.

Plays a single source identified by sourcenum or a set of sources identified by the passed sequence of source identifiers.

Sources.queue_buffers(sourcenum, buffers) → None

Queues a Buffers on a source.

Queues a Buffers instance holding one or multiple audio buffers on the source identified by sourcenum. The audio buffers in buffers will be played in sequence.

To retrieve the number of audio buffers already processed, you can query the source with the AL_BUFFERS_PROCESSED constant.

Sources.rewind(sourcenum) → None
Sources.rewind((sourcenum1, sourcenum2, ...)) → None

Rewinds a single source or a set of sources.

Rewinds a single source identified by sourcenum or a set of sources identified by the passed sequence of source identifiers.

Sources.set_prop(sourcenum, prop, value[, type]) → None

Sets the value(s) of an OpenAL property for the Sources.

Sets the value or values of a sources-related OpenAL property for the source identified by sourcenum. prop can be any valid source constant, while value must be valid for the constant.

If type is omitted, the function tries to guess, which type should be used from the passed value(s). Guessing tries to convert values implicitly, where possible, so if there are ambiguous values, it is better to provide type.

Sources.stop(sourcenum) → None
Sources.stop((sourcenum1, sourcenum2, ...)) → None

Stops playing a single source or a set of sources.

Stops playing a single source identified by sourcenum or a set of sources identified by the passed sequence of source identifiers.

Sources.unqueue_buffers(sourcenum, buffers) → None

Unqueues processed Buffers from a source

Unqueus an already processed Buffers with one or multiple audio buffers from the source identified by sourcenum.

Note

This will only succeed, when all buffers within the Buffers instance were processed by the source. Otherwise a pygame2.Error will be raised.