View source

class Audio

package s

implements Shortcut

@:directlyUsed@:build(s.shortcut.ShortcutMacro.build())@:autoBuild(s.shortcut.ShortcutMacro.build())@:build(s.shortcut.ShortcutMacro.mixinBuild())

Audio playback helper bound to a sound asset.

Audio combines sound asset loading with a playback handle and panner state. It is meant for high-level sound playback in gameplay code, where you want to point at an asset source and then control transport and panning through one object.

Typical usage:

var audio = new Audio("sfx_explosion");
audio.volume = 0.8;
audio.play();

The instance lazily waits for the asset to become available. Calls such as play are safe before loading finishes; playback begins once the underlying handle exists.

Constructor

@:value({ uncomressed : true })new(?source:String, uncomressed:Bool = true)

Creates an audio player for the given sound source.

source may be omitted and assigned later through source.

Parameters:

source

Asset source path or id.

uncomressed

Whether uncompressed playback should be preferred.

Variables

attenuationFactor:Float

Distance attenuation factor used by the panner.

Higher values usually make distance-based falloff more pronounced.

attenuationMode:AttenuationMode

Distance attenuation mode used by the panner.

This controls how volume falls off with distance.

balance:Float

Stereo balance, usually in the -1.0..1.0 range.

Negative values bias the signal left, positive values bias it right.

dopplerStrength:Float

Strength of the Doppler effect.

Set this to 0 to disable Doppler pitch shift for this player.

read onlyduration:Float

Duration of the loaded sound in seconds.

This value is only meaningful once isLoaded is true.

read onlyisLoaded:Bool

Whether the sound asset has finished loading.

location:Vec3

World-space sound position used by the panner.

This is most useful when the active backend is configured for positional audio.

maxDistance:Float

Maximum distance used for attenuation.

Past this distance the panner stops reducing volume further.

source:String

Asset source path or id.

Changing this switches the sound asset used by the player.

uncompressed:Bool

Whether the sound should be decoded to an uncompressed buffer before playback.

Use this when startup latency matters more than memory usage, or when the backend performs better with uncompressed samples. Keeping it false can reduce memory cost for larger assets when compressed playback is available.

volume:Float

Playback volume multiplier.

This affects the final channel gain and is independent from panning.

Methods

@:value({ waitForAsset : true })inlinepause(waitForAsset:Bool = true):Void

Pauses playback.

If no playback handle exists yet, this call does nothing.

Parameters:

waitForAsset

Reserved for compatibility.

@:value({ waitForAsset : true, retrigger : false })inlineplay(retrigger:Bool = false, waitForAsset:Bool = true):Void

Starts playback.

If the sound asset is not loaded yet, playback is deferred until the asset becomes available.

Parameters:

retrigger

Whether to restart playback if already playing.

waitForAsset

Reserved for compatibility with older call sites.

@:value({ waitForAsset : true })inlinestop(waitForAsset:Bool = true):Void

Stops playback.

If no playback handle exists yet, this call does nothing.

Parameters:

waitForAsset

Reserved for compatibility.