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. |
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))
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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).
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).
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.
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.
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).
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.