AudioStreamPlayer3D

package
v0.0.0-...-20ed0ac Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2025 License: MIT Imports: 28 Imported by: 0

Documentation

Overview

Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting AttenuationFilterCutoffHz to 20500.

By default, audio is heard from the camera position. This can be changed by adding an AudioListener3D node to the scene and enabling it by calling AudioListener3D.MakeCurrent on it.

See also AudioStreamPlayer to play a sound non-positionally.

Note: Hiding an AudioStreamPlayer3D node does not disable its audio output. To temporarily disable an AudioStreamPlayer3D's audio output, set VolumeDb to a very low value like -100 (which isn't audible to human hearing).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsAudioStreamPlayer3D() Instance
}

type AttenuationModel 

type AttenuationModel int //gd:AudioStreamPlayer3D.AttenuationModel

const (
	// Attenuation of loudness according to linear distance.
	AttenuationInverseDistance AttenuationModel = 0
	// Attenuation of loudness according to squared distance.
	AttenuationInverseSquareDistance AttenuationModel = 1
	// Attenuation of loudness according to logarithmic distance.
	AttenuationLogarithmic AttenuationModel = 2
	// No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer]. [AttenuationDisabled] can be combined with a [MaxDistance] value greater than 0.0 to achieve linear attenuation clamped to a sphere of a defined size.
	//
	// [AudioStreamPlayer]: https://pkg.go.dev/graphics.gd/classdb/AudioStreamPlayer
	// [MaxDistance]: https://pkg.go.dev/graphics.gd/classdb/#Instance.MaxDistance
	AttenuationDisabled AttenuationModel = 3
)

type DopplerTracking 

type DopplerTracking int //gd:AudioStreamPlayer3D.DopplerTracking

const (
	// Disables doppler tracking.
	DopplerTrackingDisabled DopplerTracking = 0
	// Executes doppler tracking during process frames (see [Node.NotificationInternalProcess]).
	DopplerTrackingIdleStep DopplerTracking = 1
	// Executes doppler tracking during physics frames (see [Node.NotificationInternalPhysicsProcess]).
	DopplerTrackingPhysicsStep DopplerTracking = 2
)

type Expanded 

type Expanded = MoreArgs

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsAudioStreamPlayer3D 

func (self *Extension[T]) AsAudioStreamPlayer3D() Instance

func (*Extension[T]) AsNode 

func (self *Extension[T]) AsNode() Node.Instance

func (*Extension[T]) AsNode3D 

func (self *Extension[T]) AsNode3D() Node3D.Instance

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.AudioStreamPlayer3D

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AreaMask 

func (self Instance) AreaMask() int

Determines which Area3D layers affect the sound for reverb and audio bus effects. Areas can be used to redirect AudioStreams so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater.

func (Instance) AsAudioStreamPlayer3D 

func (self Instance) AsAudioStreamPlayer3D() Instance

func (Instance) AsNode 

func (self Instance) AsNode() Node.Instance

func (Instance) AsNode3D 

func (self Instance) AsNode3D() Node3D.Instance

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) AttenuationFilterCutoffHz 

func (self Instance) AttenuationFilterCutoffHz() Float.X

The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to 20500 as this frequency is above the human hearing limit.

func (Instance) AttenuationFilterDb 

func (self Instance) AttenuationFilterDb() Float.X

Amount how much the filter affects the loudness, in decibels.

func (Instance) AttenuationModel 

func (self Instance) AttenuationModel() AttenuationModel

Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation.

func (Instance) Autoplay 

func (self Instance) Autoplay() bool

If true, audio plays when the AudioStreamPlayer3D node is added to scene tree.

func (Instance) Bus 

func (self Instance) Bus() string

The bus on which this audio is playing.

Note: When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to "Master".

func (Instance) DopplerTracking 

func (self Instance) DopplerTracking() DopplerTracking

Decides in which step the Doppler effect should be calculated.

Note: If DopplerTracking is not DopplerTrackingDisabled but the current Camera3D/AudioListener3D has doppler tracking disabled, the Doppler effect will be heard but will not take the movement of the current listener into account. If accurate Doppler effect is desired, doppler tracking should be enabled on both the AudioStreamPlayer3D and the current Camera3D/AudioListener3D.

func (Instance) EmissionAngleDegrees 

func (self Instance) EmissionAngleDegrees() Angle.Radians

The angle in which the audio reaches a listener unattenuated.

func (Instance) EmissionAngleEnabled 

func (self Instance) EmissionAngleEnabled() bool

If true, the audio should be attenuated according to the direction of the sound.

func (Instance) EmissionAngleFilterAttenuationDb 

func (self Instance) EmissionAngleFilterAttenuationDb() Angle.Radians

Attenuation factor used if listener is outside of EmissionAngleDegrees and EmissionAngleEnabled is set, in decibels.

func (Instance) GetPlaybackPosition 

func (self Instance) GetPlaybackPosition() Float.X

Returns the position in the AudioStream.

func (Instance) GetStreamPlayback 

func (self Instance) GetStreamPlayback() AudioStreamPlayback.Instance

Returns the AudioStreamPlayback object associated with this AudioStreamPlayer3D.

func (Instance) HasStreamPlayback 

func (self Instance) HasStreamPlayback() bool

Returns whether the AudioStreamPlayer can return the AudioStreamPlayback object or not.

func (Instance) ID 

func (self Instance) ID() ID

func (Instance) MaxDb 

func (self Instance) MaxDb() Float.X

Sets the absolute maximum of the sound level, in decibels.

func (Instance) MaxDistance 

func (self Instance) MaxDistance() Float.X

The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than 0.0. MaxDistance works in tandem with UnitSize. However, unlike UnitSize whose behavior depends on the AttenuationModel, MaxDistance always works in a linear fashion. This can be used to prevent the AudioStreamPlayer3D from requiring audio mixing when the listener is far away, which saves CPU resources.

func (Instance) MaxPolyphony 

func (self Instance) MaxPolyphony() int

The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) OnFinished 

func (self Instance) OnFinished(cb func(), flags ...Signal.Flags)

Emitted when the audio stops playing.

func (Instance) PanningStrength 

func (self Instance) PanningStrength() Float.X

Scales the panning strength for this node by multiplying the base ProjectSettings "audio/general/3d_panning_strength" by this factor. If the product is 0.0 then stereo panning is disabled and the volume is the same for all channels. If the product is 1.0 then one of the channels will be muted when the sound is located exactly to the left (or right) of the listener.

Two speaker stereo arrangements implement the WebAudio standard for StereoPannerNode Panning where the volume is cosine of half the azimuth angle to the ear.

For other speaker arrangements such as the 5.1 and 7.1 the SPCAP (Speaker-Placement Correction Amplitude) algorithm is implemented.

func (Instance) PitchScale 

func (self Instance) PitchScale() Float.X

The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.

func (Instance) Play 

func (self Instance) Play()

Queues the audio to play on the next physics frame, from the given position 'from_position', in seconds.

func (Instance) PlaybackType 

func (self Instance) PlaybackType() AudioServer.PlaybackType

The playback type of the stream player. If set other than to the default value, it will force that playback type.

func (Instance) Playing 

func (self Instance) Playing() bool

If true, audio is playing or is queued to be played (see Play).

func (Instance) SeekTo 

func (self Instance) SeekTo(to_position Float.X)

Sets the position from which audio will be played, in seconds.

func (Instance) SetAreaMask 

func (self Instance) SetAreaMask(value int)

SetAreaMask sets the property returned by [GetAreaMask].

func (Instance) SetAttenuationFilterCutoffHz 

func (self Instance) SetAttenuationFilterCutoffHz(value Float.X)

SetAttenuationFilterCutoffHz sets the property returned by [GetAttenuationFilterCutoffHz].

func (Instance) SetAttenuationFilterDb 

func (self Instance) SetAttenuationFilterDb(value Float.X)

SetAttenuationFilterDb sets the property returned by [GetAttenuationFilterDb].

func (Instance) SetAttenuationModel 

func (self Instance) SetAttenuationModel(value AttenuationModel)

SetAttenuationModel sets the property returned by [GetAttenuationModel].

func (Instance) SetAutoplay 

func (self Instance) SetAutoplay(value bool)

SetAutoplay sets the property returned by [IsAutoplayEnabled].

func (Instance) SetBus 

func (self Instance) SetBus(value string)

SetBus sets the property returned by [GetBus].

func (Instance) SetDopplerTracking 

func (self Instance) SetDopplerTracking(value DopplerTracking)

SetDopplerTracking sets the property returned by [GetDopplerTracking].

func (Instance) SetEmissionAngleDegrees 

func (self Instance) SetEmissionAngleDegrees(value Angle.Radians)

SetEmissionAngleDegrees sets the property returned by [GetEmissionAngle].

func (Instance) SetEmissionAngleEnabled 

func (self Instance) SetEmissionAngleEnabled(value bool)

SetEmissionAngleEnabled sets the property returned by [IsEmissionAngleEnabled].

func (Instance) SetEmissionAngleFilterAttenuationDb 

func (self Instance) SetEmissionAngleFilterAttenuationDb(value Angle.Radians)

SetEmissionAngleFilterAttenuationDb sets the property returned by [GetEmissionAngleFilterAttenuationDb].

func (Instance) SetMaxDb 

func (self Instance) SetMaxDb(value Float.X)

SetMaxDb sets the property returned by [GetMaxDb].

func (Instance) SetMaxDistance 

func (self Instance) SetMaxDistance(value Float.X)

SetMaxDistance sets the property returned by [GetMaxDistance].

func (Instance) SetMaxPolyphony 

func (self Instance) SetMaxPolyphony(value int)

SetMaxPolyphony sets the property returned by [GetMaxPolyphony].

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) SetPanningStrength 

func (self Instance) SetPanningStrength(value Float.X)

SetPanningStrength sets the property returned by [GetPanningStrength].

func (Instance) SetPitchScale 

func (self Instance) SetPitchScale(value Float.X)

SetPitchScale sets the property returned by [GetPitchScale].

func (Instance) SetPlaybackType 

func (self Instance) SetPlaybackType(value AudioServer.PlaybackType)

SetPlaybackType sets the property returned by [GetPlaybackType].

func (Instance) SetPlaying 

func (self Instance) SetPlaying(value bool)

SetPlaying sets the property returned by [IsPlaying].

func (Instance) SetStream 

func (self Instance) SetStream(value AudioStream.Instance)

SetStream sets the property returned by [GetStream].

func (Instance) SetStreamPaused 

func (self Instance) SetStreamPaused(value bool)

SetStreamPaused sets the property returned by [GetStreamPaused].

func (Instance) SetUnitSize 

func (self Instance) SetUnitSize(value Float.X)

SetUnitSize sets the property returned by [GetUnitSize].

func (Instance) SetVolumeDb 

func (self Instance) SetVolumeDb(value Float.X)

SetVolumeDb sets the property returned by [GetVolumeDb].

func (Instance) SetVolumeLinear 

func (self Instance) SetVolumeLinear(value Float.X)

SetVolumeLinear sets the property returned by [GetVolumeLinear].

func (Instance) Stop 

func (self Instance) Stop()

Stops the audio.

func (Instance) Stream 

func (self Instance) Stream() AudioStream.Instance

The AudioStream resource to be played.

func (Instance) StreamPaused 

func (self Instance) StreamPaused() bool

If true, the playback is paused. You can resume it by setting StreamPaused to false.

func (Instance) UnitSize 

func (self Instance) UnitSize() Float.X

The factor for the attenuation effect. Higher values make the sound audible over a larger distance.

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

func (Instance) VolumeDb 

func (self Instance) VolumeDb() Float.X

The base sound level before attenuation, in decibels.

func (Instance) VolumeLinear 

func (self Instance) VolumeLinear() Float.X

The base sound level before attenuation, as a linear value.

Note: This member modifies VolumeDb for convenience. The returned value is equivalent to the result of @GlobalScope.DbToLinear on VolumeDb. Setting this member is equivalent to setting VolumeDb to the result of @GlobalScope.LinearToDb on a value.

type MoreArgs 

type MoreArgs [1]gdclass.AudioStreamPlayer3D

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) Play 

func (self MoreArgs) Play(from_position Float.X)

Queues the audio to play on the next physics frame, from the given position 'from_position', in seconds.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.