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.

See also

free

Free cached audio resources given their names

Buffer.destroy

Free the buffer’s cache

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.

Raises

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