AudioEngine class abstract Audio

The audio playback system for a subtree of the scene graph.

Attach a concrete AudioEngine subclass (from a backend package) to a node, typically the scene root, before mounting sources. Descendant AudioSource components and AudioListeners resolve the nearest ancestor engine on mount; a source mounted with no ancestor engine stays inert.

Each frame the scene driver syncs the listener and lets the backend flush. The listener is the first mounted AudioListener in the engine's subtree; with none mounted, the ears follow the scene's primary camera, so spatial audio works with no listener setup.

Backends implement clip loading (loadClip), voice creation (createVoice), bus creation (onCreateBus), and the per-frame hooks (onSyncListener, onFrameCommit). App-lifecycle policy (pausing playback while backgrounded, platform audio-session setup) is a backend concern; see the backend package's documentation.

Inheritance

• Object
• Component
• AudioEngine

Constructors

AudioEngine()

Properties

activeListener → AudioListener?

The listener whose node currently provides the ears, or null when the engine is following the camera fallback.

no setter

backendName → String

Identifier of the concrete backend, suitable for logging (for example "soloud").

no setter

enabled ↔ bool

Whether this component's update hook runs each frame.

getter/setter pair, inherited

hashCode → int

The hash code for this object.

no setter, inherited

isAttached → bool

Whether this component is currently attached to a node.

no setter, inherited

isLoaded → bool

Whether onLoad has completed.

no setter, inherited

isMounted → bool

Whether the owning node is part of a live scene graph.

no setter, inherited

masterBus → AudioBus

The root of the bus hierarchy. Every voice not routed elsewhere plays through it.

no setter

masterVolume ↔ double

Gain applied to all playback. Shorthand for the master bus volume.

getter/setter pair

node → Node

The node this component is attached to.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

cloneFor(Node cloneOwner) → Component?

Returns a copy of this component for cloneOwner, the Node.clone counterpart of the owning node, or null to not carry the component to clones (the default).

inherited

createBus(String name, {AudioBus? parent}) → AudioBus

Creates a named mix bus routed into parent (the master bus when null). Names must be unique; "master" is reserved.

createVoice(AudioClip clip) → AudioVoice

Creates a paused single-use voice playing clip. See AudioVoice for the configure-then-AudioVoice.start flow. Throws when the engine is not ready or clip is disposed.

findBus(String name) → AudioBus?

Returns the bus created with createBus under name, the master bus for "master", or null.

fixedUpdate(double fixedDt) → void

Called once per fixed physics step while the component is mounted, enabled, and loaded. fixedDt is the fixed timestep of the surrounding PhysicsWorld, not the frame interval.

inherited

loadClip(String assetKey) → Future<AudioClip>

Loads and decodes an audio asset (a Flutter asset key) into a playable clip. Completes after the engine finishes initializing.

loadClipFromBytes(String key, Uint8List bytes) → Future<AudioClip>

Loads and decodes in-memory encoded audio bytes (any container the backend decodes, typically wav/ogg/mp3) into a playable clip, for downloaded or generated audio. key names the clip for backend bookkeeping and should be unique per logical clip. Completes after the engine finishes initializing.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

onAttach() → void

Called when this component is added to a node.

inherited

onCreateBus(String name, AudioBus parent) → AudioBus

Backend hook creating the concrete bus. Called by createBus.

onDetach() → void

Called when this component is removed from a node.

inherited

onFrameCommit(double deltaSeconds) → void

Backend hook run once per frame after the listener and all source transforms are current. Backends that batch native commands flush here.

onLoad() → Future<void>

Optional asynchronous setup, such as loading an asset.

inherited

onMount() → void

Called when the owning node enters a live scene graph.

inherited

onSyncListener(Vector3 position, Vector3 forward, Vector3 up, Vector3 velocity) → void

Backend hook receiving this frame's listener pose (world space).

onUnmount() → void

Called when the owning node leaves a live scene graph.

inherited

playOneShot(AudioClip clip, {Vector3? position, double volume = 1.0, double pitch = 1.0, AudioBus? bus, AudioAttenuation? attenuation}) → AudioVoice

Plays clip once, fire and forget. With a position the sound is spatialized there (stationary); without one it plays flat. The returned voice can adjust or stop the playback.

toString() → String

A string representation of this object.

inherited

update(double deltaSeconds) → void

Called once per frame while the component is mounted, enabled, and loaded. deltaSeconds is the elapsed time since the previous tick.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Methods

findAncestor(Node node) → AudioEngine?

Returns the nearest AudioEngine on node or an ancestor, or null.