simvx.core._audio_stream

Audio stream/data layer: :class:AudioStream resource + container detection.

Private leaf module behind the :mod:simvx.core.audio facade. Holds the audio data concerns: the :class:AudioStream resource handle, the header-probe container detection helpers, the WAV data chunk seek helper, and the sample-rate/channel constants and type aliases that belong to this layer. The playback mixin and the player nodes live in sibling _audio_playback / _audio_players modules.

Module Contents

Classes

AudioStream

Audio resource (WAV/OGG file or synthetic PCM).

Data

AudioSource

AudioContainer

log

API

simvx.core._audio_stream.AudioSource

None

simvx.core._audio_stream.AudioContainer

None

simvx.core._audio_stream.log

‘getLogger(…)’

class simvx.core._audio_stream.AudioStream(source: simvx.core._audio_stream.AudioSource)[source]

Audio resource (WAV/OGG file or synthetic PCM).

This is a lightweight handle to audio data. Actual decoding is deferred to the backend (miniaudio, SDL3, web audio).

Accepts any of:

  • class:

    str / :class:os.PathLike – a filesystem audio file.

  • class:

    ~simvx.core.Resource – audio inside a Python package.

  • class:

    importlib.resources.abc.Traversable – the raw return of importlib.resources.files(pkg) / name.

Use :meth:tone for procedural sine-wave tones and :meth:from_pcm to wrap pre-rendered PCM data.

Attributes: source: Original spec the stream was constructed from – a string, :class:pathlib.Path, :class:Resource, or :class:Traversable. Preserved verbatim so scene serialisation can round-trip it. path: Resolved filesystem path string used by the backend (empty string for synthetic streams that have no file). backend_data: Backend-specific audio data (PCM ndarray, channel id, etc). Set automatically when decoded; may also be set by :meth:from_pcm / :meth:tone. container: Detected container format – one of "wav", "ogg", "mp3", "flac", "pcm" (synthetic) or "unknown". Probed from the file header at construction time; the streaming open path uses it to pick the right decoder.

Initialization

__slots__

(‘source’, ‘_path’, ‘backend_data’, ‘sample_rate’, ‘channels’, ‘_container’)

property path: str[source]

Resolved filesystem path string used by the backend.

Synthetic streams (from_pcm / tone / empty) carry their assigned name here. The dual-field design (separate source + path slots both holding the same string for synthetic streams) was collapsed during the audio refactor; path is now a derived attribute backed by _path.

property container: simvx.core._audio_stream.AudioContainer[source]

Detected container format. See :data:AudioContainer for the value set.

__repr__()[source]
classmethod tone(freq_hz: float, *, duration: float = 1.0, volume: float = 0.3, sample_rate: int = _SAMPLE_RATE) → simvx.core._audio_stream.AudioStream[source]

Generate a sine-wave tone at freq_hz with a short fade-in/out.

The resulting stream has its PCM data baked into backend_data so the audio backend skips file decoding entirely.

classmethod from_pcm(samples: numpy.ndarray, *, sample_rate: int, channels: int, name: str = 'pcm') → simvx.core._audio_stream.AudioStream[source]

Wrap a pre-rendered PCM buffer as an AudioStream.

Args: samples: float32 ndarray. For stereo, interleaved (channels first within each frame); for mono, a 1-D array. sample_rate: PCM sample rate in Hz. Required: playing a 44.1 kHz buffer on a 48 kHz backend produces wrong-pitch audio if this is omitted. channels: 1 (mono) or 2 (stereo). Required for the same reason: a mono buffer played as stereo gives left-channel-only sound. name: Descriptive label used in :meth:__repr__ and as the stream’s path. The backend ignores it when backend_data is set.

Raises: InvalidStreamError: sample_rate <= 0 or channels is not 1 or 2. TypeError: samples isn’t a numpy ndarray.

classmethod empty(*, name: str = 'empty') → simvx.core._audio_stream.AudioStream[source]

Return a synthetic stream with no audio data.

Used internally by :meth:AudioSynth.bake (before it overwrites the synthetic frame buffer) and by null-backend tests that need a placeholder stream object without touching the filesystem. The returned stream carries container="pcm" and backend_data=None: playing it through a real backend is undefined.

Replaces the legacy AudioStream("") sentinel.