libretro.api.audio¶

Audio callback and sample rendering types.

Corresponds to retro_audio_callback and related types in libretro.h. These types allow cores to push audio samples to the frontend or to be notified of audio buffer status changes.

See also

AudioDriver: The protocol that uses these types to implement audio output support in libretro.py.
libretro.drivers.audio: libretro.py’s included AudioDriver implementations.

Module Attributes

`retro_audio_sample_t`	Render a single stereo audio frame.
`retro_audio_sample_batch_t`	Render multiple stereo audio frames at once.
`retro_audio_callback_t`	Render audio samples on demand.
`retro_audio_set_state_callback_t`	Notify the core that audio rendering should start or stop.
`retro_audio_buffer_status_callback_t`	Report the frontend's audio buffer occupancy to the core.

Classes

`retro_audio_buffer_status_callback`	Core-registered callback for audio buffer status reporting.
`retro_audio_callback`	Core-registered callbacks for asynchronous audio rendering.

retro_audio_sample_t¶

Render a single stereo audio frame.

Called by the core to push one signed 16-bit sample per channel to the frontend.

Parameters:

left – Signed 16-bit sample for the left channel.
right – Signed 16-bit sample for the right channel.

Corresponds to retro_audio_sample_t in libretro.h.

See also

Core.set_audio_sample(): The method that exposes this callback to cores.
AudioDriver.sample(): The method that implements this callback in libretro.py.

retro_audio_sample_batch_t¶

Render multiple stereo audio frames at once.

Called by the core to push a buffer of interleaved signed 16-bit left/right samples (i.e. [L, R, L, R, ...]) to the frontend.

Parameters:

data – Pointer to a buffer of interleaved signed 16-bit samples.
frames – Number of stereo frames in data (i.e. half the number of samples).

Returns:

The number of frames that were processed by the frontend.

Corresponds to retro_audio_sample_batch_t in libretro.h.

See also

Core.set_audio_sample_batch(): The method that exposes this callback to cores.
AudioDriver.sample_batch(): The method that implements this callback in libretro.py.

retro_audio_callback_t¶

Render audio samples on demand.

Registered by the core and called by the frontend when it is ready to receive audio output; the core should respond by pushing samples through retro_audio_sample_t or retro_audio_sample_batch_t.

Warning

The frontend may invoke this callback from any thread, so its implementation must be thread-safe.

Corresponds to retro_audio_callback_t in libretro.h.

See also

AudioDriver.callback(): The suggested entry point for this registered callback in libretro.py.

retro_audio_set_state_callback_t¶

Notify the core that audio rendering should start or stop.

Registered by the core and called by the frontend to indicate whether the audio driver is currently active.

Parameters:: enabled – True if the frontend’s audio driver is active and ready to receive samples, False if it is paused.

Corresponds to retro_audio_set_state_callback_t in libretro.h.

See also

AudioDriver.set_state(): The suggested entry point for this registered callback in libretro.py.

retro_audio_buffer_status_callback_t¶

Report the frontend’s audio buffer occupancy to the core.

Registered by the core and called by the frontend right before each frame so the core can react to impending buffer underruns (for example, by skipping a frame).

Parameters:

active – True if the frontend’s audio buffer is currently in use, False if audio is disabled.
occupancy – Audio buffer occupancy as a percentage in the range [0, 100].
underrun_likely – True if the frontend expects an audio buffer underrun on the next frame.

Corresponds to retro_audio_buffer_status_callback_t in libretro.h.

See also

AudioDriver.report_buffer_status(): The suggested entry point for this registered callback in libretro.py.

class retro_audio_callback[source]¶

Bases: Structure

Core-registered callbacks for asynchronous audio rendering.

Corresponds to retro_audio_callback in libretro.h.

callback¶: Called by the frontend to request audio samples from the core.

set_state¶: Called by the frontend to notify the core whether audio output is active.

__deepcopy__(_)[source]¶

Return a copy of this struct. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_audio_callback
>>> cb = retro_audio_callback()
>>> cb_copy = copy.deepcopy(cb)
>>> cb_copy == cb
True
>>> cb_copy is cb
False

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class retro_audio_buffer_status_callback[source]¶

Bases: Structure

Core-registered callback for audio buffer status reporting.

Corresponds to retro_audio_buffer_status_callback in libretro.h.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

callback¶: Called to inform the core of the audio buffer’s occupancy.

self(active, occupancy, underrun_likely)[source]¶

Call callback with the given parameters if non-None, otherwise does nothing.

Parameters:

active (bool) – Whether audio is active.
occupancy (int) – The current audio buffer occupancy.
underrun_likely (bool) – Whether an underrun is likely.

Return type:

None

>>> from libretro.api import retro_audio_buffer_status_callback
>>> cb = retro_audio_buffer_status_callback()
>>> cb(True, 50, False)  # No-op since callback is None

__deepcopy__(_)[source]¶

Return a copy of this struct with the same callback. Intended for use with copy.deepcopy().

>>> import copy
>>> from libretro.api import retro_audio_buffer_status_callback
>>> cb = retro_audio_buffer_status_callback()
>>> cb_copy = copy.deepcopy(cb)
>>> cb_copy == cb
True
>>> cb_copy is cb
False