palace.Buffer¶Buffer of preloaded PCM samples coming from a Decoder.
-Cached buffers must be freed using destroy before destroying -context. Alternatively, this can be used as a context manager -that calls destroy upon completion of the block, +
Buffer of preloaded PCM samples coming from a Decoder.
Cached buffers must be freed using destroy before destroying
+context. Alternatively, this can be used as a context manager
+that calls destroy upon completion of the block,
even if an error occurs.
name (str) – Audio file or resource name. Multiple calls with the same name will return the same buffer.
context (Optional[Context], optional) – The context from which the buffer is to be created and cached. -By default current_context() is used.
current_context() is used.
destroy() → None¶Free the buffer’s cache.
-This invalidates all other Buffer objects with the same name.
+This invalidates all other Buffer objects with the same name.
name (str) – The name to give to the buffer. It may alias an audio file, but it must not currently exist in the buffer cache.
context (Optional[Context], optional) – The context from which the buffer is to be created. -By default current_context() is used.
current_context() is used.
RuntimeError – If there is neither any context specified nor current; - or if name is already used for another buffer.
+ or ifname is already used for another buffer.
loop_points¶Loop points for looping sources.
-If AL_SOFT_loop_points extension is not supported by the -current context, start = 0 and end = length respectively. -Otherwise, start < end <= length.
+If AL_SOFT_loop_points extension is not supported by the
+current context, start = 0 and end = length respectively.
+Otherwise, start < end <= length.
play(source: Optional[palace.Source]) → palace.Source¶Play source using the buffer.
-Return the source used for playing. If None is given, +
Play source using the buffer.
Return the source used for playing. If None is given,
create a new one.
One buffer may be played from multiple sources simultaneously.
Storage size used by the buffer, in bytes.
Notes
The size in bytes may not be what you expect from the length, -as it may take more space internally than the channel_config -and sample_type suggest.
+as it may take more space internally than thechannel_config
+and sample_type suggest.
source_count¶
Number of sources currently using the buffer.
Notes
-Context.update needs to be called to reliably ensure the count +
Context.update needs to be called to reliably ensure the count
is kept updated for when sources reach their end. This is
-equivalent to calling len(self.sources).
len(self.sources).
The resources will be scheduled for caching asynchronously,
and should be retrieved later when needed by initializing
-Buffer corresponding objects. Resources that cannot be
+Buffer corresponding objects. Resources that cannot be
loaded, for example due to an unsupported format, will be
-ignored and a later Buffer initialization will raise
+ignored and a later Buffer initialization will raise
an exception.
If context is not given, current_context() will be used.
+If context is not given, current_context() will be used.
RuntimeError – If there is neither any context specified nor current.
@@ -299,7 +299,7 @@ an exception.palace.free(names: Iterable[str], context: Optional[palace.Context] = None) → None¶Free cached audio resources given their names.
-If context is not given, current_context() will be used.
+If context is not given, current_context() will be used.
RuntimeError – If there is neither any context specified nor current.
diff --git a/reference/context.html b/reference/context.html index d3208ae..2180f3a 100644 --- a/reference/context.html +++ b/reference/context.html @@ -138,7 +138,7 @@ such as sources, buffers and effects.available_resamplers¶The list of resamplers supported by the context.
-If AL_SOFT_source_resampler extension is unsupported, +
If AL_SOFT_source_resampler extension is unsupported,
this will be an empty list. Otherwise there would be
at least one entry.
This method require the context to be current.
@@ -190,7 +190,7 @@ at least one entry.default_resampler_index¶The context’s default resampler index.
-If AL_SOFT_source_resampler extension is unsupported, +
If AL_SOFT_source_resampler extension is unsupported,
this will return 0.
If you try to access the resampler list with this index without extension, undefined behavior will occur @@ -218,7 +218,7 @@ closer than its reference distance or farther than its max distance.
ValueError – If set to a preset cannot be found in distance_models.
+ValueError – If set to a preset cannot be found in distance_models.
The default is 343.3 units per second (a realistic speed
assuming 1 meter per unit). If this is adjusted for a
-different unit scale, Listener.meters_per_unit should
+different unit scale, Listener.meters_per_unit should
also be adjusted.
palace.Listener¶
Listener instance of the given context.
It is recommended that applications access the listener via
-Context.listener, which avoid the overhead caused by the
+Context.listener, which avoid the overhead caused by the
creation of the wrapper object.
context (Optional[Context], optional) – The context on which the listener instance is to be created. -By default current_context() is used.
+By defaultcurrent_context() is used.
RuntimeError – If there is neither any context specified nor current.
@@ -312,7 +312,7 @@ By default current_context() is used.This is used for various effects relying on the distance
in meters including air absorption and initial reverb decay.
If this is changed, so should the speed of sound
-(e.g. context.speed_of_sound = 343.3 / meters_per_unit
+(e.g. context.speed_of_sound = 343.3 / meters_per_unit
to maintain a realistic 343.3 m/s for sound propagation).
Applications may derive from this and set an instance on a context to receive messages. The base methods are no-ops, so subclasses only need to implement methods for relevant messages.
-Exceptions raised from MessageHandler instances are ignored.
+Exceptions raised from MessageHandler instances are ignored.
buffer_loading(name: str, channel_config: str, sample_type: str, sample_rate: int, data: Sequence[int]) → None¶name (str) – Resource name passed to Buffer.
name (str) – Resource name passed to Buffer.
channel_config (str) – Channel configuration of the given audio data.
sample_type (str) – Sample type of the given audio data.
sample_rate (int) – Sample rate of the given audio data.
device_disconnected(device: palace.Device) → None¶
Handle disconnected device messages.
This is called when the given device has been disconnected and
-is no longer usable for output. As per ALC_EXT_disconnect
+is no longer usable for output. As per ALC_EXT_disconnect
specification, disconnected devices remain valid, however all
playing sources are automatically stopped, any sources that are
attempted to play will immediately stop, and new contexts may
not be created on the device.
Notes
-Connection status is checked during Context.update calls, so +
Connection status is checked during Context.update calls, so
method must be called regularly to be notified when a device is
disconnected. This method may not be called if the device lacks
-support for ALC_EXT_disconnect extension.
ALC_EXT_disconnect extension.
resource_not_found(name: str) → str¶Return the fallback resource for the one of the given name.
-This is called when name is not found, allowing substitution +
This is called when name is not found, allowing substitution
of a different resource until the returned string either points
to a valid resource or is empty (default).
For buffers being cached, the original name will still be used @@ -416,9 +416,9 @@ because of one of the following reasons:
There were no more mixing sources and a higher-priority source preempted it.
source is part of a SourceGroup (or sub-group thereof) -that had its SourceGroup.stop_all method called.
source was playing a buffer that’s getting removed.
source is part of a SourceGroup (or sub-group thereof)
+that had its SourceGroup.stop_all method called.
source was playing a buffer that’s getting removed.
source_stopped(source: palace.Source) → None¶
Handle end-of-buffer/stream messages.
This is called when the given source reaches the end of buffer -or stream, which is detected upon a call to Context.update.
+or stream, which is detected upon a call toContext.update.
palace.use_context(context: Optional[palace.Context], thread: Optional[bool] = None) → None¶
Make the specified context current for OpenAL operations.
This fails silently if the given context has been destroyed. -In case thread is not specified, fallback to preference made by -thread_local.
-If thread is True, make the context current
+In case thread is not specified, fallback to preference made by
+thread_local.
If thread is True, make the context current
for OpenAL operations on the calling thread only.
This requires the non-device-specific as well as the context’s
-device ALC_EXT_thread_local_context extension to be available.
ALC_EXT_thread_local_context extension to be available.
palace.current_context(thread: Optional[bool] = None) → Optional[palace.Context]¶Return the context that is currently used.
-If thread is set to True, return the thread-specific context +
If thread is set to True, return the thread-specific context
used for OpenAL operations. This requires the non-device-specific
-as well as the context’s device ALC_EXT_thread_local_context
+as well as the context’s device ALC_EXT_thread_local_context
extension to be available.
In case thread is not specified, fallback to preference made by -thread_local.
+In case thread is not specified, fallback to preference made by
+thread_local.
palace.thread_local(state: bool) → Iterator[None]¶Return a context manager controlling preference of local thread.
-Effectively, it sets fallback value for thread argument -for current_context and use_context.
-Initially, globally current Context is preferred.
+Effectively, it sets fallback value for thread argument
+for current_context and use_context.
Initially, globally current Context is preferred.
name (str) – Audio file or resource name.
context (Optional[Context], optional) – The context from which the decoder is to be created. -By default current_context() is used.
current_context() is used.
See also
Notes
Due to implementation details, while this creates decoder objects
from filenames using contexts, it is the superclass of the ABC
-(abstract base class) BaseDecoder. Because of this, Decoder
+(abstract base class) BaseDecoder. Because of this, Decoder
may only initialize an internal one. To use registered factories,
-please call the module-level decode function instead.
decode function instead.
channel_config¶length¶
Length of audio in sample frames, falling-back to 0.
Notes
-Zero-length decoders may not be used to load a Buffer.
+Zero-length decoders may not be used to load a Buffer.
length_seconds¶
Length of audio in seconds, falling-back to 0.0.
Notes
-Zero-length decoders may not be used to load a Buffer.
+Zero-length decoders may not be used to load a Buffer.
Notes
-If start >= end, all available samples are included +
If start >= end, all available samples are included
in the loop.
play(chunk_len: int, queue_size: int, source: Optional[palace.Source]) → palace.Source¶Stream audio asynchronously from the decoder.
-The decoder must NOT have its read or seek called +
The decoder must NOT have its read or seek called
from elsewhere while in use.
queue_size (int) – The number of chunks to keep queued during playback. Smaller values use less memory while larger values improve protection against underruns.
source (Optional[Source], optional) – The source object to play audio. If None is given, +
source (Optional[Source], optional) – The source object to play audio. If None is given,
a new one will be created from the current context.
read(count: int) → bytes¶Decode and return count sample frames.
+Decode and return count sample frames.
If less than the requested count samples is returned, the end of the audio has been reached.
seek(pos: int) → bool¶Seek to pos, specified in sample frames.
+Seek to pos, specified in sample frames.
Return if the seek was successful.
palace.BaseDecoder(*args, **kwargs)¶
Audio decoder interface.
Applications may derive from this, implement necessary methods, -and use it in places the API wants a BaseDecoder object.
-Exceptions raised from BaseDecoder instances are ignored.
+and use it in places the API wants aBaseDecoder object.
+Exceptions raised from BaseDecoder instances are ignored.
channel_config¶length¶
Length of audio in sample frames, falling-back to 0.
Notes
-Zero-length decoders may not be used to load a Buffer.
+Zero-length decoders may not be used to load a Buffer.
Notes
-If start >= end, all available samples are included +
If start >= end, all available samples are included
in the loop.
read(count: int) → bytes¶Decode and return count sample frames.
+Decode and return count sample frames.
If less than the requested count samples is returned, the end of the audio has been reached.
palace.Device¶Audio mix output, via either a system stream or a hardware port.
-This can be used as a context manager that calls close upon +
This can be used as a context manager that calls close upon
completion of the block, even if an error occurs.
current_hrtf¶Name of the HRTF currently being used by this device.
-If HRTF is not currently enabled, this will be None.
+If HRTF is not currently enabled, this will be None.
efx_version¶EFX version supported by this device.
-If ALC_EXT_EFX extension is unsupported, this will be (0, 0).
+If ALC_EXT_EFX extension is unsupported, this will be (0, 0).
hrtf_enabled¶Whether HRTF is enabled on the device.
-If ALC_SOFT_HRTF extension is unavailable, +
If ALC_SOFT_HRTF extension is unavailable,
this will return False although there could still be
HRTF applied at a lower hardware level.
hrtf_names¶
List of available HRTF names.
The order is retained from OpenAL, such that the index of -a given name is the ID to use with ALC_HRTF_ID_SOFT.
-If ALC_SOFT_HRTF extension is unavailable,
+a given name is the ID to use with ALC_HRTF_ID_SOFT.
If ALC_SOFT_HRTF extension is unavailable,
this will be an empty list.
max_auxiliary_sends¶Maximum number of auxiliary source sends.
-If ALC_EXT_EFX is unsupported, this will be 0.
+If ALC_EXT_EFX is unsupported, this will be 0.
pause_dsp() → None¶
Pause device processing and stop contexts’ updates.
Multiple calls are allowed but it is not reference counted, -so the device will resume after one resume_dsp call.
-This requires ALC_SOFT_pause_device extension.
+so the device will resume after oneresume_dsp call.
+This requires ALC_SOFT_pause_device extension.
reset(attrs: Dict[int, int]) → None¶Reset the device, using the specified attributes.
-If ALC_SOFT_HRTF extension is unavailable, +
If ALC_SOFT_HRTF extension is unavailable,
this will be a no-op.
Instances of this class has no effect (pun intended).
It takes the output mix of zero or more sources, applies DSP for the desired effect, then adds to the output mix.
-This can be used as a context manager that calls destroy +
This can be used as a context manager that calls destroy
upon completion of the block, even if an error occurs.
context (Optional[Context], optional) – The context from which the effect is to be created. -By default current_context() is used.
+By defaultcurrent_context() is used.
RuntimeError – If there is neither any context specified nor current.
@@ -168,7 +168,7 @@ it will be removed first.use_count¶Number of source sends the effect slot is used by.
-This is equivalent to calling len(self.source_sends).
+This is equivalent to calling len(self.source_sends).
feedback (float) – From -1.0 to 1.0.
delay (float) – From 0.0 to 0.016.
context (Optional[Context], optional) – The context from which the effect is to be created. -By default current_context() is used.
current_context() is used.
preset (str, optional) – The initial preset to start with, falling back to GENERIC.
context (Optional[Context], optional) – The context from which the effect is to be created. -By default current_context() is used.
current_context() is used.
ValueError – If the specified preset cannot be found in reverb_preset_names.
ValueError – If the specified preset cannot be found in reverb_preset_names.
RuntimeError – If there is neither any context specified nor current.
palace.current_fileio() → Optional[Callable[[str], palace.FileIO]]¶Return the file I/O factory currently in used by audio decoders.
-If the default is being used, return None.
+If the default is being used, return None.
palace.use_fileio(factory: Optional[Callable[[str], FileIO]], buffer_size: int = 8192) → None¶Set the file I/O factory instance to be used by audio decoders.
-If factory=None is provided, revert to the default.
+If factory=None is provided, revert to the default.
palace.FileIO(*args, **kwargs)¶
File I/O protocol.
This static duck type defines methods required to be used by
-palace decoders. Despite its name, a FileIO is not necessarily
+palace decoders. Despite its name, a FileIO is not necessarily
created from a file, but any seekable finite input stream.
Many classes defined in the standard library module io +
Many classes defined in the standard library module io
are compatible with this protocol.
Notes
Since PEP 544 is only implemented in Python 3.8+, type checking
diff --git a/reference/source.html b/reference/source.html
index 3d40961..515e037 100644
--- a/reference/source.html
+++ b/reference/source.html
@@ -119,13 +119,13 @@
class palace.Source¶
Sound source for playing audio.
There is no practical limit to the number of sources one may create.
-When the source is no longer needed, destroy must be called, +
When the source is no longer needed, destroy must be called,
unless the context manager is used, which guarantees the source’s
destructioni upon completion of the block, even if an error occurs.
context (Optional[Context], optional) – The context from which the source is to be created. -By default current_context() is used.
+By defaultcurrent_context() is used.
RuntimeError – If there is neither any context specified nor current.
@@ -150,12 +150,12 @@ foggy air and lower values simulating dryer air; default to 0.inner (float) – The area within which the listener will hear the source without extra attenuation, default to 360.
outer (float) – The area outside of which the listener will hear the source -attenuated according to outer_cone_gains, default to 360.
outer_cone_gains, default to 360.
ValueError – If set to a value where inner is greater than outer +
ValueError – If set to a value where inner is greater than outer
or either of them is outside of the [0, 360] interval.
ValueError – If set to a value where refdist is greater than maxdist +
ValueError – If set to a value where refdist is greater than maxdist
or either of them is outside of the [0, FLT_MAX] interval.
fade_out_to_stop(gain: float, ms: int) → None¶Fade the source to gain over ms milliseconds.
-gain is in addition to the base gain and must be within -the [0, 1] interval. ms must be positive.
+Fade the source to gain over ms milliseconds.
gain is in addition to the base gain and must be within
+the [0, 1] interval. ms must be positive.
The fading is logarithmic. As a result, the initial drop-off may happen faster than expected but the fading is more perceptually consistant over the given duration. It will take just as much time to go from -6 dB to -12 dB as it will to go from -40 dB to -46 dB, for example.
-Fading is updated during calls to Context.update, +
Fading is updated during calls to Context.update,
which should be called regularly (30 to 50 times per second)
for the fading to be smooth.
direct_hf (bool) – Direct path’s high frequency gain, default to True.
send (bool) – Send paths’ gain, default to True.
send_hf (bool) – Send paths’ high-frequency, default to True.
direct_hf (bool) – Direct path’s high frequency gain, default to True.
send (bool) – Send paths’ gain, default to True.
send_hf (bool) – Send paths’ high-frequency, default to True.
ValueError – If set to a value where mingain is greater than maxgain +
ValueError – If set to a value where mingain is greater than maxgain
or either of them is outside of the [0, 1] interval.
group¶
Parent group of this source.
The parent group influences all sources that belong to it.
-A source may only be the child of one SourceGroup at a time,
+A source may only be the child of one SourceGroup at a time,
although that source group may belong to another source group.
This is None when the source does not belong to any group. -On the other hand, setting it to None removes the source +
This is None when the source does not belong to any group.
+On the other hand, setting it to None removes the source
from its current group.
See also
SourceGroupA group of Source references
+SourceGroupA group of Source references
latency¶Source latency in nanoseconds.
-If AL_SOFT_source_latency extension is unsupported, +
If AL_SOFT_source_latency extension is unsupported,
this will be 0.
latency_seconds¶Source latency in seconds.
-If AL_SOFT_source_latency extension is unsupported, +
If AL_SOFT_source_latency extension is unsupported,
this will be 0.
Notes
-Unlike AL_EXT_BFORMAT extension this property +
Unlike AL_EXT_BFORMAT extension this property
comes from, this also affects the facing direction.
gain (float) – Linear gain applying to all frequencies, default to 1.
gain_hf (float) – Linear gain applying extra attenuation to high frequencies creating a low-pass effect, default to 1. It has no effect -without the ALC_EXT_EFX extension.
ALC_EXT_EFX extension.
@@ -434,7 +434,7 @@ sources are played.
radius¶Radius of the source, as if it is a sound-emitting sphere.
-This has no effect without AL_EXT_SOURCE_RADIUS extension.
+This has no effect without AL_EXT_SOURCE_RADIUS extension.
ValueError – If set to a negative value.
@@ -446,8 +446,8 @@ sources are played.relative¶Whether the source’s 3D parameters are relative to listener.
-The affected parameters includes position, velocity, -and orientation.
+The affected parameters includes position, velocity,
+and orientation.
resampler_index¶
Index of the resampler to use for this source.
The index must be nonnegative, from the resamplers returned -by Context.get_available_resamplers, and has no effect -without the AL_SOFT_source_resampler extension.
+byContext.get_available_resamplers, and has no effect
+without the AL_SOFT_source_resampler extension.
sends¶
Collection of send path signals.
Send paths can be retrieved using a nonnegative index, which has -no effect if not less than the device’s max_auxiliary_sends.
+no effect if not less than the device’smax_auxiliary_sends.
Each send path has two write-only descriptors, -effect and filter.
+effect and filter.
Examples
>>> source.sends[0].effect = effect
>>> source.sends[1].filter = 1, 0.6, 0.9
@@ -507,12 +507,12 @@ no effect if not less than the device’s max_auxiliary_sends.
spatialize¶Whether to enable 3D spatialization.
-Either True (the source always has 3D spatialization -features), False (never has 3D spatialization features), -or None (spatialization is enabled based on playing +
Either True (the source always has 3D spatialization
+features), False (never has 3D spatialization features),
+or None (spatialization is enabled based on playing
a mono sound or not, default).
This has no effect without -AL_SOFT_source_spatialize extension.
+AL_SOFT_source_spatialize extension.
The angles go counter-clockwise, with 0 being in front and positive values going left.
This is only used for stereo playback and has no effect -without AL_EXT_STEREO_ANGLES extension.
+withoutAL_EXT_STEREO_ANGLES extension.
palace.SourceGroup¶A group of Source references.
-For instance, setting SourceGroup.gain to 0.5 will halve the gain +
A group of Source references.
For instance, setting SourceGroup.gain to 0.5 will halve the gain
of all sources in the group.
This can be used as a context manager that calls destroy upon +
This can be used as a context manager that calls destroy upon
completion of the block, even if an error occurs.
context (Optional[Context], optional) – The context from which the source group is to be created. -By default current_context() is used.
+By defaultcurrent_context() is used.
RuntimeError – If there is neither any context specified nor current.