Resource Caching¶

Audio Buffers¶

class 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, even if an error occurs.

Parameters

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.

name¶

Audio file or resource name.

Type: str

Raises: RuntimeError – If there is neither any context specified nor current.

property channel_config¶: Buffer’s sample configuration.

destroy() → None¶

Free the buffer’s cache.

This invalidates all other Buffer objects with the same name.

property frequency¶: Buffer’s frequency in hertz.

static from_decoder(decoder: palace.Decoder, name: str, context: Optional[palace.Context]) → palace.Buffer ¶

Return a buffer created by reading the given decoder.

Parameters

decoder (Decoder) – The decoder from which the buffer is to be cached.
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.

Raises

RuntimeError – If there is neither any context specified nor current; or if name is already used for another buffer.

property length¶: Length of the buffer in sample frames.

property length_seconds¶: Length of the buffer in seconds.

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.

Returns

start (int) – Starting point, in sample frames (inclusive).
end (int) – Ending point, in sample frames (exclusive).

Note

The buffer must not be in use when this property is set.

play(source: Optional[palace.Source]) → palace.Source ¶

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.

property sample_type¶: Buffer’s sample type.

property size¶: Storage size used by the buffer, in bytes.

Note

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.

property source_count¶: Number of sources currently using the buffer.

Note

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

property sources¶: Source objects currently playing the buffer.

Loading & Freeing in Batch¶

palace.cache(names: Iterable[str], context: Optional[palace.Context] = None) → None¶

Cache given audio resources asynchronously.

Duplicate names and buffers already cached are ignored. Cached buffers must be freed before destroying the context.

The resources will be scheduled for caching asynchronously, and should be retrieved later when needed by initializing 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 an exception.

If context is not given, current_context() will be used.

Raises: RuntimeError – If there is neither any context specified nor current.