`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, AudioStreamPlayer2D, AudioStreamPlayer3D

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

# 2D sound effect
sfx = AudioStreamPlayer2D(stream="audio://sfx/explosion.wav", position=Vec2(100, 50))
sfx.play()

# 3D spatial audio
engine = AudioStreamPlayer3D(stream="audio://sfx/engine.ogg", position=Vec3(10, 0, 5))
engine.play()

Module Contents¶

Classes¶

`AudioStream`	Audio resource (WAV/OGG file).
`AudioListener`	Singleton that tracks the active camera for 3D audio spatialization.
`AudioStreamPlayer`	Non-positional audio player for background music and UI sounds.
`AudioStreamPlayer2D`	2D positional audio player with stereo panning.
`AudioStreamPlayer3D`	3D spatial audio player with distance attenuation and directional panning.

Data¶

`log`
`__all__`

API¶

simvx.core.audio.log¶: ‘getLogger(…)’

simvx.core.audio.__all__¶: [‘AudioStream’, ‘AudioStreamPlayer’, ‘AudioStreamPlayer2D’, ‘AudioStreamPlayer3D’, ‘AudioListener’]

class simvx.core.audio.AudioStream(path: str)¶

Audio resource (WAV/OGG file).

This is a lightweight handle to audio data. Actual loading is deferred to the backend (SDL_mixer, OpenAL, etc).

Attributes: path: File path or URI (e.g., “audio://music/theme.ogg”) resource_uri: Full URI if loaded via ResourceCache backend_data: Backend-specific audio data (channel, source ID, etc)

Initialization

__slots__¶: (‘path’, ‘resource_uri’, ‘backend_data’)

__repr__()¶

class simvx.core.audio.AudioListener¶

Singleton that tracks the active camera for 3D audio spatialization.

The listener position is automatically updated from Camera3D or Camera2D by the backend’s audio system.

Initialization

classmethod get() → simvx.core.audio.AudioListener¶

classmethod reset()¶: Reset singleton (useful for tests).

class simvx.core.audio.AudioStreamPlayer(stream: str | simvx.core.audio.AudioStream | None = None, **kwargs)¶

Bases: simvx.core.audio._AudioPlaybackMixin, simvx.core.engine.Node

Non-positional audio player for background music and UI sounds.

This player does not use 3D positioning — volume is constant regardless of camera position. Use AudioStreamPlayer2D or AudioStreamPlayer3D for spatial audio.

Settings: volume_db: Volume in decibels (-80 to 24). 0 = full volume. pitch_scale: Playback speed multiplier (0.5 to 2.0). bus: Audio bus name (“master”, “music”, “sfx”, etc). autoplay: Start playing when added to scene tree. loop: Loop playback when finished. stream_mode: “memory” loads entire file; “streaming” reads in chunks. buffer_size: Chunk size in bytes for streaming mode (default 64KB).

Initialization

volume_db¶: ‘Property(…)’

pitch_scale¶: ‘Property(…)’

bus¶: ‘Property(…)’

autoplay¶: ‘Property(…)’

loop¶: ‘Property(…)’

stream_mode¶: ‘Property(…)’

buffer_size¶: ‘Property(…)’

ready()¶

process(delta: float)¶: Feed audio chunks to backend in streaming mode.

play(from_position: float = 0.0)¶

Start or resume playback.

Args: from_position: Start position in seconds (0.0 = beginning).

stop()¶: Stop playback and reset position to beginning.

get_playback_position() → float¶: Get current playback position in seconds.

pause()¶

is_playing() → bool¶

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

reset_error() → None¶

add_child(node: simvx.core.node.Node) → simvx.core.node.Node¶

remove_child(node: simvx.core.node.Node)¶

reparent(new_parent: simvx.core.node.Node)¶

get_node(path: str) → simvx.core.node.Node¶

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None¶

find(node_type: type) → simvx.core.node.Node | None¶

find_all(node_type: type, recursive: bool = True) → list¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

enter_tree() → None¶

exit_tree() → None¶

physics_process(dt: float) → None¶

draw(renderer) → None¶

input_event(event: simvx.core.events.InputEvent) → None¶

input(event: simvx.core.events.TreeInputEvent) → None¶

unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle¶

stop_coroutine(gen_or_handle)¶

destroy()¶

queue_free¶: None

property tree: simvx.core.scene_tree.SceneTree¶

get_tree() → simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]¶

get_settings¶: None

__repr__()¶

class simvx.core.audio.AudioStreamPlayer2D(stream: str | simvx.core.audio.AudioStream | None = None, **kwargs)¶

Bases: simvx.core.audio._AudioPlaybackMixin, simvx.core.engine.Node2D

2D positional audio player with stereo panning.

Audio volume and pan are calculated based on distance from the 2D listener (typically Camera2D position). Left/right panning simulates direction.

Settings: volume_db: Base volume in decibels (-80 to 24). pitch_scale: Playback speed multiplier (0.5 to 2.0). bus: Audio bus name. autoplay: Start playing when added to scene tree. loop: Loop playback when finished. max_distance: Distance at which audio is inaudible (pixels). attenuation: Distance attenuation exponent (1.0 = linear, 2.0 = inverse square).

Initialization

volume_db¶: ‘Property(…)’

pitch_scale¶: ‘Property(…)’

bus¶: ‘Property(…)’

autoplay¶: ‘Property(…)’

loop¶: ‘Property(…)’

max_distance¶: ‘Property(…)’

attenuation¶: ‘Property(…)’

ready()¶

process(delta: float)¶: Update 2D spatialization each frame.

play(from_position: float = 0.0)¶: Start or resume playback.

stop()¶

pause()¶

is_playing() → bool¶

z_index¶: ‘Property(…)’

z_as_relative¶: ‘Property(…)’

property absolute_z_index: int¶

property position: simvx.core.math.types.Vec2¶

property rotation: float¶

property rotation_degrees: float¶

property scale: simvx.core.math.types.Vec2¶

property global_position: simvx.core.math.types.Vec2¶

property global_rotation: float¶

property global_scale: simvx.core.math.types.Vec2¶

property forward: simvx.core.math.types.Vec2¶

property right: simvx.core.math.types.Vec2¶

translate(offset: tuple[float, float] | numpy.ndarray)¶

rotate(radians: float)¶

rotate_deg(degrees: float)¶

look_at(target: tuple[float, float] | numpy.ndarray)¶

transform_points(points: list[simvx.core.math.types.Vec2]) → list[simvx.core.math.types.Vec2]¶

draw_polygon(renderer, points: list[simvx.core.math.types.Vec2], closed=True, color=None)¶

wrap_screen(margin: float = 20)¶

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

reset_error() → None¶

add_child(node: simvx.core.node.Node) → simvx.core.node.Node¶

remove_child(node: simvx.core.node.Node)¶

reparent(new_parent: simvx.core.node.Node)¶

get_node(path: str) → simvx.core.node.Node¶

find_child(name: str, recursive: bool = False) → simvx.core.node.Node | None¶

find(node_type: type) → simvx.core.node.Node | None¶

find_all(node_type: type, recursive: bool = True) → list¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

enter_tree() → None¶

exit_tree() → None¶

physics_process(dt: float) → None¶

draw(renderer) → None¶

input_event(event: simvx.core.events.InputEvent) → None¶

input(event: simvx.core.events.TreeInputEvent) → None¶

unhandled_input(event: simvx.core.events.TreeInputEvent) → None¶

start_coroutine(gen: simvx.core.descriptors.Coroutine) → simvx.core.descriptors.CoroutineHandle¶

stop_coroutine(gen_or_handle)¶

destroy()¶

queue_free¶: None

property tree: simvx.core.scene_tree.SceneTree¶

get_tree() → simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

classmethod get_properties() → dict[str, simvx.core.descriptors.Property]¶

get_settings¶: None

__repr__()¶

class simvx.core.audio.AudioStreamPlayer3D(stream: str | simvx.core.audio.AudioStream | None = None, **kwargs)¶

Bases: simvx.core.audio._AudioPlaybackMixin, simvx.core.engine.Node3D

3D spatial audio player with distance attenuation and directional panning.

Audio volume and stereo panning are calculated based on distance and direction from the 3D listener (typically Camera3D position/orientation).

Settings: volume_db: Base volume in decibels (-80 to 24). pitch_scale: Playback speed multiplier (0.5 to 2.0). bus: Audio bus name. autoplay: Start playing when added to scene tree. loop: Loop playback when finished. max_distance: Distance at which audio is inaudible (world units). attenuation: Distance attenuation exponent (1.0 = linear, 2.0 = inverse square). doppler_scale: Doppler effect strength (0.0 = off, 1.0 = realistic).

Initialization