Source code for simvx.core.audio

"""
Audio system: background music, UI sounds, and 3D spatial audio.

This module provides:
- AudioClip: Audio resource (WAV/OGG data)
- AudioPlayer: Background music/UI sounds
- AudioPlayer2D: 2D positional audio with panning
- AudioPlayer3D: 3D spatial audio with attenuation

Public API::

    from simvx.core import AudioClip, AudioPlayer, Resource

    # Filesystem audio file
    player = AudioPlayer(stream="music/theme.ogg", autoplay=True)

    # Asset shipped inside a Python package
    sfx = AudioPlayer2D(stream=Resource("game.assets", "explosion.wav"))
    sfx.play()

    # Synthetic procedural tone
    beep = AudioPlayer(stream=AudioClip.tone(440))
    beep.play()

This module is a thin facade. The implementation lives in private leaf
modules: ``_audio_stream`` (the :class:`AudioClip` resource + container
detection / WAV seek helpers), ``_audio_playback`` (the shared
:class:`_AudioPlaybackMixin`), and ``_audio_players`` (the three player
nodes). Import the public names from here or from :mod:`simvx.core`.
"""

from __future__ import annotations

from ._audio_playback import _AudioPlaybackMixin
from ._audio_players import AudioPlayer, AudioPlayer2D, AudioPlayer3D
from ._audio_stream import (
    AudioContainer,
    AudioSource,
    AudioClip,
    _detect_container_from_bytes,
    _detect_container_from_path,
    _seek_wav_data_chunk,
)

# These names are part of the historical ``simvx.core.audio`` surface and are
# imported directly from this module by tests and adjacent code. They are
# re-exported here (rather than only from the private leaves) so those import
# sites keep resolving. ``__all__`` intentionally lists only the public API.
__all__ = [
    "AudioClip",
    "AudioPlayer",
    "AudioPlayer2D",
    "AudioPlayer3D",
]

# Re-exports kept off ``__all__`` but referenced so linters don't strip them.
_REEXPORTS = (
    _AudioPlaybackMixin,
    AudioContainer,
    AudioSource,
    _detect_container_from_bytes,
    _detect_container_from_path,
    _seek_wav_data_chunk,
)