`simvx.core._audio_players`¶

Audio player nodes: :class:AudioStreamPlayer / 2D / 3D.

Private leaf module behind the :mod:simvx.core.audio facade. The player node classes compose the shared :class:_AudioPlaybackMixin with the node base classes and add the non-positional / 2D / 3D playback specifics. The shared playback state machine lives in _audio_playback; the stream/data layer in _audio_stream.

Module Contents¶

Classes¶

`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

API¶

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

class simvx.core._audio_players.AudioStreamPlayer(stream: simvx.core._audio_stream.AudioSource | simvx.core._audio_stream.AudioStream | None = None, **kwargs)[source]¶

Bases: simvx.core._audio_playback._AudioPlaybackMixin, simvx.core.node.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. One of "Master", "Music", "SFX", "Voice", "UI" (case-sensitive, Godot convention). 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(…)’

queue_free_on_end¶: ‘Property(…)’

stream_mode¶: ‘Property(…)’

buffer_size¶: ‘Property(…)’

stream_open_failed¶: ‘Signal(…)’

on_ready()[source]¶

on_process(delta: float)[source]¶: Feed audio chunks to backend in streaming mode; tick fades; auto-free.

play(from_position: float = 0.0)[source]¶

Start or resume playback.

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

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

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

pause()¶

is_playing() → bool¶

is_paused() → bool¶

fade_out(seconds: float) → None¶

fade_in(seconds: float) → None¶

pitch_modulate(scale: float) → None¶

crossfade_to(other: simvx.core._audio_playback._AudioPlaybackMixin, seconds: float) → None¶

strict_errors: ClassVar[bool]¶: True

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

property visible: bool¶

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(target: type | str, recursive: bool = True) → simvx.core.node.Node | None¶

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

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

on_enter_tree() → None¶

on_exit_tree() → None¶

on_physics_process(dt: float) → None¶

on_draw(renderer) → None¶

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

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

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

stop_coroutine(gen_or_handle)¶

clear_children()¶

destroy()¶

property app¶

property tree: simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

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

__repr__()¶

class simvx.core._audio_players.AudioStreamPlayer2D(stream: simvx.core._audio_stream.AudioSource | simvx.core._audio_stream.AudioStream | None = None, **kwargs)[source]¶

Bases: simvx.core._audio_playback._AudioPlaybackMixin, simvx.core.nodes_2d.node2d.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(…)’

queue_free_on_end¶: ‘Property(…)’

max_distance¶: ‘Property(…)’

attenuation¶: ‘Property(…)’

pan_override¶: ‘Property(…)’

gizmo_colour¶: ‘Colour(…)’

get_gizmo_lines() → list[tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2]][source]¶: Return circle showing the audio range.

on_ready()[source]¶

set_pan_and_gain(pan: float, gain_db: float) → None[source]¶

Atomically set pan_override + volume_db with one backend call.

Use when both must land on the same audio frame (e.g. fade-out before retrigger). Setting them as separate Property assignments would fire two backend updates.

on_process(delta: float)[source]¶: Update 2D spatialization each frame; tick fades; auto-free.

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

stop()¶

pause()¶

is_playing() → bool¶

is_paused() → bool¶

fade_out(seconds: float) → None¶

fade_in(seconds: float) → None¶

pitch_modulate(scale: float) → None¶

crossfade_to(other: simvx.core._audio_playback._AudioPlaybackMixin, seconds: float) → None¶

position¶: ‘_SpatialVecProperty(…)’

rotation¶: ‘Property(…)’

scale¶: ‘_SpatialVecProperty(…)’

z_index¶: ‘Property(…)’

z_as_relative¶: ‘Property(…)’

render_layer¶: ‘Property(…)’

set_render_layer(index: int, enabled: bool = True) → None¶

is_on_render_layer(index: int) → bool¶

property absolute_z_index: int¶

property rotation_degrees: float¶

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

property world_rotation: float¶

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

property world_transform: tuple[simvx.core.math.types.Vec2, simvx.core.math.types.Vec2, float]¶

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, colour=None)¶

wrap_screen(margin: float = 20)¶

strict_errors: ClassVar[bool]¶: True

script_error_raised¶: ‘Signal(…)’

classmethod __init_subclass__(**kwargs)¶

property name: str¶

property process_mode: simvx.core.descriptors.ProcessMode¶

property visible: bool¶

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(target: type | str, recursive: bool = True) → simvx.core.node.Node | None¶

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

walk(*, include_self: bool = True) → collections.abc.Iterator[simvx.core.node.Node]¶

property path: str¶

add_to_group(group: str)¶

remove_from_group(group: str)¶

is_in_group(group: str) → bool¶

on_enter_tree() → None¶

on_exit_tree() → None¶

on_physics_process(dt: float) → None¶

on_draw(renderer) → None¶

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

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

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

stop_coroutine(gen_or_handle)¶

clear_children()¶

destroy()¶

property app¶

property tree: simvx.core.scene_tree.SceneTree¶

__getitem__(key: str)¶

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

__repr__()¶

class simvx.core._audio_players.AudioStreamPlayer3D(stream: simvx.core._audio_stream.AudioSource | simvx.core._audio_stream.AudioStream | None = None, **kwargs)[source]¶

Bases: simvx.core._audio_playback._AudioPlaybackMixin, simvx.core.nodes_3d.node3d.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