Source code for simvx.core.audio

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

This module provides:
- AudioStream: Audio resource (WAV/OGG data)
- AudioStreamPlayer: Background music/UI sounds
- AudioStreamPlayer2D: 2D positional audio with panning
- AudioStreamPlayer3D: 3D spatial audio with attenuation

Public API::

    from simvx.core import AudioStream, AudioStreamPlayer, Resource

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

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

    # Synthetic procedural tone
    beep = AudioStreamPlayer(stream=AudioStream.tone(440))
    beep.play()

This module is a thin facade. The implementation lives in private leaf
modules: ``_audio_stream`` (the :class:`AudioStream` 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 AudioStreamPlayer, AudioStreamPlayer2D, AudioStreamPlayer3D
from ._audio_stream import (
    AudioContainer,
    AudioSource,
    AudioStream,
    _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__ = [
    "AudioStream",
    "AudioStreamPlayer",
    "AudioStreamPlayer2D",
    "AudioStreamPlayer3D",
]

# 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,
)