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.
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
may only initialize an internal one. To use registered factories, please call the module-leveldecode
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.
Notes
Zero-length decoders may not be used to load a
Buffer
.
-
property
length_seconds
¶ Length of audio in seconds, falling-back to 0.0.
Notes
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.
Notes
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
orseek
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.
Notes
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.
Notes
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.
-
abstract property
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.