AudioStreamPlayer2D

Home | API by Category | Complete API Index | API Compatibility

Field	Value
Full name	Electron2D.AudioStreamPlayer2D
Namespace	Electron2D
Kind	class
Category	Audio

Overview

Plays an Electron2D.AudioStream as a sound source in 2D space.

Syntax

public class Electron2D.AudioStreamPlayer2D : Electron2D.Node2D

Godot 4.7 C# profile compatibility

Profile: Electron2D 0.1.0 2D
Status: Partial / Not verified
Out of profile: yes
Godot reference: AudioStreamPlayer2D

2D playback node with the shared playback API plus bus selection, distance attenuation and left/right panning.

Remarks

Electron2D.AudioStreamPlayer2D uses the node's Electron2D.Node2D.GlobalPosition to calculate distance attenuation and stereo panning before starting an internal voice.

Electron2D 0.1.0 Preview uses the origin of the 2D world as the listener position. Dedicated listener nodes and area-based routing are future audio tasks.

Thread Safety

This type is not synchronized. Create and mutate it on the main scene thread that owns the node.

Since

This class is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStream
• Electron2D.AudioStreamPlayer
• Electron2D.Node2D

Members

Member	Kind	Summary
AreaMask	Property	Gets or sets which 2D area layers may affect this audio source.
Attenuation	Property	Gets or sets the distance attenuation exponent.
Autoplay	Property	Gets or sets whether this node starts playback when it enters a scene tree.
Bus	Property	Gets or sets the target audio bus name.
MaxDistance	Property	Gets or sets the maximum distance from which this source is still audible.
MaxPolyphony	Property	Gets or sets the maximum number of simultaneous voices owned by this node.
PanningStrength	Property	Gets or sets the strength of left/right panning.
PitchScale	Property	Gets or sets the playback pitch scale.
Playing	Property	Gets or sets whether this player is currently requested to play.
Stream	Property	Gets or sets the stream resource played by this node.
StreamPaused	Property	Gets or sets whether playback is paused.
VolumeDb	Property	Gets or sets the playback volume in decibels before 2D attenuation.
VolumeLinear	Property	Gets or sets the playback volume as linear gain before 2D attenuation.
Electron2D.AudioStreamPlayer2D()	Constructor	Initializes a new instance of the Electron2D.AudioStreamPlayer2D class.
GetPlaybackPosition()	Method	Gets the stored playback position.
HasStreamPlayback()	Method	Checks whether this player currently owns an active stream voice.
Play(System.Single)	Method	Starts playback from a position in the stream.
Seek(System.Single)	Method	Changes the stored playback position.
Stop()	Method	Stops all voices owned by this player.

Member Details

AreaMask

Kind: Property

public System.Int32 AreaMask { get; set; }

Summary

Gets or sets which 2D area layers may affect this audio source.

Remarks

Area-based audio routing is not active in 0.1.0 Preview. The value is stored for scene data compatibility with the selected public API subset.

Value

A non-negative bit mask. The default value is 0.

Exceptions

• System.ArgumentOutOfRangeException: Thrown when the value is negative.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D

Attenuation

Kind: Property

public System.Single Attenuation { get; set; }

Summary

Gets or sets the distance attenuation exponent.

Remarks

Higher values make the sound fade faster as distance approaches Electron2D.AudioStreamPlayer2D.MaxDistance.

Value

A finite non-negative exponent. The default value is 1.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.
• System.ArgumentOutOfRangeException: Thrown when the value is negative.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.MaxDistance

Autoplay

Kind: Property

public System.Boolean Autoplay { get; set; }

Summary

Gets or sets whether this node starts playback when it enters a scene tree.

Remarks

Autoplay only starts when Electron2D.AudioStreamPlayer2D.Stream is assigned. Removing the node from the tree stops voices owned by this player.

Value

true to call Electron2D.AudioStreamPlayer2D.Play(System.Single) on enter-tree; otherwise false.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Play(System.Single)

Bus

Kind: Property

public Electron2D.StringName Bus { get; set; }

Summary

Gets or sets the target audio bus name.

Remarks

Electron2D.AudioServer resolves this name when playback starts. If the name does not match an existing bus, the voice falls back to Master.

Value

The requested bus name. The default value is Master.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioServer.GetBusName(System.Int32)
• Electron2D.AudioServer.SetBusName(System.Int32,System.String)
• Electron2D.AudioServer.SetBusSend(System.Int32,Electron2D.StringName)

MaxDistance

Kind: Property

public System.Single MaxDistance { get; set; }

Summary

Gets or sets the maximum distance from which this source is still audible.

Remarks

A value of 0 disables distance attenuation and panning for this preview implementation.

Value

A finite non-negative distance in 2D units. The default value is 2000.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.
• System.ArgumentOutOfRangeException: Thrown when the value is negative.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Attenuation
• Electron2D.AudioStreamPlayer2D.PanningStrength

MaxPolyphony

Kind: Property

public System.Int32 MaxPolyphony { get; set; }

Summary

Gets or sets the maximum number of simultaneous voices owned by this node.

Remarks

When the limit is reached, the next Electron2D.AudioStreamPlayer2D.Play(System.Single) call stops the oldest voice owned by this player before starting a new one.

Value

The maximum polyphony count. The default value is 1.

Exceptions

• System.ArgumentOutOfRangeException: Thrown when the value is less than 1.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Play(System.Single)

PanningStrength

Kind: Property

public System.Single PanningStrength { get; set; }

Summary

Gets or sets the strength of left/right panning.

Remarks

The computed pan is clamped to -1 through 1 before being sent to the internal voice.

Value

A finite non-negative panning multiplier. The default value is 1.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.
• System.ArgumentOutOfRangeException: Thrown when the value is negative.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.MaxDistance

PitchScale

Kind: Property

public System.Single PitchScale { get; set; }

Summary

Gets or sets the playback pitch scale.

Remarks

A value of 1 plays the stream at its original pitch.

Value

A positive finite multiplier applied to stream pitch and tempo.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.
• System.ArgumentOutOfRangeException: Thrown when the value is less than or equal to 0.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.VolumeDb

Playing

Kind: Property

public System.Boolean Playing { get; set; }

Summary

Gets or sets whether this player is currently requested to play.

Remarks

Setting this property to true calls Electron2D.AudioStreamPlayer2D.Play(System.Single). Setting it to false calls Electron2D.AudioStreamPlayer2D.Stop.

Value

true when playback is active or paused; otherwise false.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.StreamPaused

Stream

Kind: Property

public Electron2D.AudioStream Stream { get; set; }

Summary

Gets or sets the stream resource played by this node.

Remarks

Setting this property stops all voices currently owned by this player.

Value

The stream resource to play, or null when no stream is assigned.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Play(System.Single)

StreamPaused

Kind: Property

public System.Boolean StreamPaused { get; set; }

Summary

Gets or sets whether playback is paused.

Remarks

Pausing stops active voices but keeps Electron2D.AudioStreamPlayer2D.Playing true. Clearing this property resumes from the stored playback position when a stream is assigned.

Value

true when playback should pause and resume later; otherwise false.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Playing

VolumeDb

Kind: Property

public System.Single VolumeDb { get; set; }

Summary

Gets or sets the playback volume in decibels before 2D attenuation.

Remarks

The value is combined with distance attenuation when Electron2D.AudioStreamPlayer2D.Play(System.Single) starts a voice.

Value

A finite decibel offset applied to the stream.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.VolumeLinear

VolumeLinear

Kind: Property

public System.Single VolumeLinear { get; set; }

Summary

Gets or sets the playback volume as linear gain before 2D attenuation.

Remarks

Setting this property updates Electron2D.AudioStreamPlayer2D.VolumeDb.

Value

A finite non-negative linear gain. The default value is 1.

Exceptions

• System.ArgumentException: Thrown when the value is not finite.
• System.ArgumentOutOfRangeException: Thrown when the value is negative.

Thread Safety

This property is not synchronized. Access it from the main scene thread.

Since

This property is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.VolumeDb

Electron2D.AudioStreamPlayer2D()

Kind: Constructor

public Electron2D.AudioStreamPlayer2D()

Summary

Initializes a new instance of the Electron2D.AudioStreamPlayer2D class.

Remarks

The new player has no stream assigned, targets the Master bus and registers the finished signal.

Thread Safety

This constructor is not synchronized. Call it from the main scene thread.

Since

This constructor is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Stream

GetPlaybackPosition()

Kind: Method

public System.Single GetPlaybackPosition()()

Summary

Gets the stored playback position.

Remarks

The preview runtime stores the last requested start or seek position. It does not expose backend clock advancement as public API.

Returns

The stored playback position in seconds.

Thread Safety

This method is not synchronized. Call it from the main scene thread.

Since

This method is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Seek(System.Single)

HasStreamPlayback()

Kind: Method

public System.Boolean HasStreamPlayback()()

Summary

Checks whether this player currently owns an active stream voice.

Remarks

This method returns false while Electron2D.AudioStreamPlayer2D.StreamPaused is true.

Returns

true when at least one internal voice owned by this player is active; otherwise false.

Thread Safety

This method is not synchronized. Call it from the main scene thread.

Since

This method is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Playing

Play(System.Single)

Kind: Method

public System.Void Play(System.Single)(System.Single fromPosition)

Summary

Starts playback from a position in the stream.

Remarks

Calling this method creates a new 2D voice when Electron2D.AudioStreamPlayer2D.Stream is assigned. The voice receives volume attenuation and pan calculated from the node position.

Parameters

• fromPosition: The stream position, in seconds, where playback should begin.

Exceptions

• System.ArgumentException: Thrown when fromPosition is not finite.
• System.ArgumentOutOfRangeException: Thrown when fromPosition is negative.

Thread Safety

This method is not synchronized. Call it from the main scene thread.

Since

This method is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Seek(System.Single)
• Electron2D.AudioStreamPlayer2D.Stop

Seek(System.Single)

Kind: Method

public System.Void Seek(System.Single)(System.Single toPosition)

Summary

Changes the stored playback position.

Remarks

If playback is active and not paused, this method restarts the active voice from toPosition.

Parameters

• toPosition: The stream position, in seconds, to seek to.

Exceptions

• System.ArgumentException: Thrown when toPosition is not finite.
• System.ArgumentOutOfRangeException: Thrown when toPosition is negative.

Thread Safety

This method is not synchronized. Call it from the main scene thread.

Since

This method is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.GetPlaybackPosition

Stop()

Kind: Method

public System.Void Stop()()

Summary

Stops all voices owned by this player.

Remarks

The stored playback position is reset to 0. Calling Electron2D.AudioStreamPlayer2D.Stop does not emit the finished signal.

Thread Safety

This method is not synchronized. Call it from the main scene thread.

Since

This method is available since Electron2D 0.1.0 Preview.

See Also

• Electron2D.AudioStreamPlayer2D.Play(System.Single)