Audio Streams

Builtin Decoders

class palace.Decoder

Generic audio decoder.

Parameters

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

Raises

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

See also

Buffer

Preloaded PCM samples coming from a Decoder

Note

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 may only initialize an internal one. To use registered factories, please call the module-level decode function instead.

property channel_config

Channel configuration of the audio being decoded.

property frequency

Sample frequency, in hertz, of the audio being decoded.

property length

Length of audio in sample frames, falling-back to 0.

Note

Zero-length decoders may not be used to load a Buffer.

property length_seconds

Length of audio in seconds, falling-back to 0.0.

Note

Zero-length decoders may not be used to load a Buffer.

property loop_points

Loop points in sample frames.

Returns

• start (int) – Inclusive starting loop point.

• end (int) – Exclusive starting loop point.

Note

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 from elsewhere while in use.

Parameters

• chunk_len (int) – The number of sample frames to read for each chunk update. Smaller values will require more frequent updates and larger values will handle more data with each chunk.

• 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, a new one will be created from the current context.

Returns

Return type

The source used for playing.

read(count: int) → bytes

Decode and return count sample frames.

If less than the requested count samples is returned, the end of the audio has been reached.

See also

sample_length

length of samples of given size

property sample_type

Sample type of the audio being decoded.

seek(pos: int) → bool

Seek to pos, specified in sample frames.

Return if the seek was successful.

Decoder Interface

palace.decoder_factories: DecoderNamespace

Simple object for storing decoder factories.

User-registered factories are tried one after another if RuntimeError is raised, in lexicographical order. Internal decoder factories are always used after registered ones.

palace.decode(name: str, context: Optional[palace.Context] = None) → palace.Decoder

Return the decoder created from the given resource name.

This first tries user-registered decoder factories in lexicographical order, then fallback to the internal ones.

Raises

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

See also

decoder_factories

Simple object for storing decoder factories

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

abstract property channel_config

Channel configuration of the audio being decoded.

abstract property frequency

Sample frequency, in hertz, of the audio being decoded.

abstract property length

Length of audio in sample frames, falling-back to 0.

Note

Zero-length decoders may not be used to load a Buffer.

abstract property loop_points

Loop points in sample frames.

Returns

• start (int) – Inclusive starting loop point.

• end (int) – Exclusive starting loop point.

Note

If start >= end, all available samples are included in the loop.

abstract read(count: int) → bytes

Decode and return count sample frames.

If less than the requested count samples is returned, the end of the audio has been reached.

abstract property sample_type

Sample type of the audio being decoded.

abstract seek(pos: int) → bool

Seek to pos, specified in sample frames.

Return if the seek was successful.

Miscellaneous

palace.sample_types: Tuple[str, …]

Names of available sample types.

palace.channel_configs: Tuple[str, …]

Names of available channel configurations.

palace.sample_size(length: int, channel_config: str, sample_type: str) → int

Return the size of the given number of sample frames.

Raises

• ValueError – If either channel_config or sample_type is invalid.

• RuntimeError – If the byte size result too large.

palace.sample_length(size: int, channel_config: str, sample_type: str) → int

Return the number of frames stored in the given byte size.

Raises

ValueError – If either channel_config or sample_type is invalid.

Environmental Effects File I/O Interface