Document the SDL audio module.

Author: HexDecimal

docs/index.rst

@@ -39,6 +39,7 @@ Contents:
     tcod/render
     tcod/tileset
     libtcodpy
+    sdl/audio
     sdl/render
     sdl/mouse
     sdl/video

docs/sdl/audio.rst

@@ -0,0 +1,5 @@
+tcod.sdl.audio - SDL Audio
+==========================
+
+.. automodule:: tcod.sdl.audio
+    :members:

tcod/sdl/audio.py

@@ -1,3 +1,7 @@
+"""SDL2 audio playback and recording tools.
+
+.. versionadded:: unreleased
+"""
 from __future__ import annotations
 
 import enum
@@ -8,7 +12,7 @@
 
 import numpy as np
 from numpy.typing import ArrayLike, DTypeLike, NDArray
-from typing_extensions import Literal
+from typing_extensions import Final, Literal
 
 import tcod.sdl.sys
 from tcod.loader import ffi, lib
@@ -52,7 +56,10 @@ def _dtype_from_format(format: int) -> np.dtype[Any]:
 
 
 class AudioDevice:
-    """An SDL audio device."""
+    """An SDL audio device.
+
+    Open new audio devices using :any:`tcod.sdl.audio.open`.
+    """
 
     def __init__(
         self,
@@ -63,20 +70,30 @@ def __init__(
         assert device_id >= 0
         assert ffi.typeof(spec) is ffi.typeof("SDL_AudioSpec*")
         assert spec
-        self.device_id = device_id
-        self.spec = spec
-        self.frequency = spec.freq
-        self.is_capture = capture
-        self.format = _dtype_from_format(spec.format)
-        self.channels = int(spec.channels)
-        self.silence = int(spec.silence)
-        self.samples = int(spec.samples)
-        self.buffer_size = int(spec.size)
+        self.device_id: Final[int] = device_id
+        """The SDL device identifier used for SDL C functions."""
+        self.spec: Final[Any] = spec
+        """The SDL_AudioSpec as a CFFI object."""
+        self.frequency: Final[int] = spec.freq
+        """The audio device sound frequency."""
+        self.is_capture: Final[bool] = capture
+        """True if this is a recording device instead of an output device."""
+        self.format: Final[np.dtype[Any]] = _dtype_from_format(spec.format)
+        """The format used for audio samples with this device."""
+        self.channels: Final[int] = int(spec.channels)
+        """The number of audio channels for this device."""
+        self.silence: float = int(spec.silence)
+        """The value of silence, according to SDL."""
+        self.buffer_samples: Final[int] = int(spec.samples)
+        """The size of the audio buffer in samples."""
+        self.buffer_bytes: Final[int] = int(spec.size)
+        """The size of the audio buffer in bytes."""
         self._handle: Optional[Any] = None
         self._callback: Callable[[AudioDevice, NDArray[Any]], None] = self.__default_callback
 
     @property
     def callback(self) -> Callable[[AudioDevice, NDArray[Any]], None]:
+        """If the device was opened with a callback enabled, then you may get or set the callback with this attribute."""
         if self._handle is None:
             raise TypeError("This AudioDevice was opened without a callback.")
         return self._callback
@@ -89,6 +106,7 @@ def callback(self, new_callback: Callable[[AudioDevice, NDArray[Any]], None]) ->
 
     @property
     def _sample_size(self) -> int:
+        """The size of a sample in bytes."""
         return self.format.itemsize * self.channels
 
     @property
@@ -119,9 +137,15 @@ def _convert_array(self, samples_: ArrayLike) -> NDArray[Any]:
         return np.ascontiguousarray(np.broadcast_to(samples, (samples.shape[0], self.channels)), dtype=self.format)
 
     @property
-    def queued_audio_bytes(self) -> int:
+    def _queued_bytes(self) -> int:
+        """The current amount of bytes remaining in the audio queue."""
         return int(lib.SDL_GetQueuedAudioSize(self.device_id))
 
+    @property
+    def queued_samples(self) -> int:
+        """The current amount of samples remaining in the audio queue."""
+        return self._queued_bytes // self._sample_size
+
     def queue_audio(self, samples: ArrayLike) -> None:
         """Append audio samples to the audio data queue."""
         assert not self.is_capture
@@ -132,7 +156,7 @@ def queue_audio(self, samples: ArrayLike) -> None:
     def dequeue_audio(self) -> NDArray[Any]:
         """Return the audio buffer from a capture stream."""
         assert self.is_capture
-        out_samples = self.queued_audio_bytes // self._sample_size
+        out_samples = self._queued_bytes // self._sample_size
         out = np.empty((out_samples, self.channels), self.format)
         buffer = ffi.from_buffer(out)
         bytes_returned = lib.SDL_DequeueAudio(self.device_id, buffer, len(buffer))
@@ -144,11 +168,11 @@ def __del__(self) -> None:
         self.close()
 
     def close(self) -> None:
-        """Close this audio device."""
-        if not self.device_id:
+        """Close this audio device.  Using this object after it has been closed is invalid."""
+        if not hasattr(self, "device_id"):
             return
         lib.SDL_CloseAudioDevice(self.device_id)
-        self.device_id = 0
+        del self.device_id
 
     @staticmethod
     def __default_callback(device: AudioDevice, stream: NDArray[Any]) -> None:
@@ -218,9 +242,11 @@ def __init__(self, device: AudioDevice):
         self.device = device
 
     def run(self) -> None:
-        buffer = np.full((self.device.samples, self.device.channels), self.device.silence, dtype=self.device.format)
+        buffer = np.full(
+            (self.device.buffer_samples, self.device.channels), self.device.silence, dtype=self.device.format
+        )
         while True:
-            if self.device.queued_audio_bytes > 0:
+            if self.device._queued_bytes > 0:
                 time.sleep(0.001)
                 continue
             self.on_stream(buffer)

tcod/sdl/sys.py

@@ -9,14 +9,14 @@
 
 
 class Subsystem(enum.IntFlag):
-    TIMER = lib.SDL_INIT_TIMER or 0x00000001
-    AUDIO = lib.SDL_INIT_AUDIO or 0x00000010
-    VIDEO = lib.SDL_INIT_VIDEO or 0x00000020
-    JOYSTICK = lib.SDL_INIT_JOYSTICK or 0x00000200
-    HAPTIC = lib.SDL_INIT_HAPTIC or 0x00001000
-    GAMECONTROLLER = lib.SDL_INIT_GAMECONTROLLER or 0x00002000
-    EVENTS = lib.SDL_INIT_EVENTS or 0x00004000
-    SENSOR = getattr(lib, "SDL_INIT_SENSOR", None) or 0x00008000  # SDL >= 2.0.9
+    TIMER = 0x00000001
+    AUDIO = 0x00000010
+    VIDEO = 0x00000020
+    JOYSTICK = 0x00000200
+    HAPTIC = 0x00001000
+    GAMECONTROLLER = 0x00002000
+    EVENTS = 0x00004000
+    SENSOR = 0x00008000
     EVERYTHING = lib.SDL_INIT_EVERYTHING or 0
 
 
@@ -49,11 +49,11 @@ def __exit__(self, *args: Any) -> None:
 
 
 class _PowerState(enum.IntEnum):
-    UNKNOWN = getattr(lib, "SDL_POWERSTATE_UNKNOWN", 0)
-    ON_BATTERY = getattr(lib, "SDL_POWERSTATE_ON_BATTERY", 0)
-    NO_BATTERY = getattr(lib, "SDL_POWERSTATE_NO_BATTERY", 0)
-    CHARGING = getattr(lib, "SDL_POWERSTATE_CHARGING", 0)
-    CHARGED = getattr(lib, "SDL_POWERSTATE_CHARGED", 0)
+    UNKNOWN = 0
+    ON_BATTERY = enum.auto()
+    NO_BATTERY = enum.auto()
+    CHARGING = enum.auto()
+    CHARGED = enum.auto()
 
 
 def _get_power_info() -> Tuple[_PowerState, int, int]: