Class AudioSource

Plays audio clips in the scene, with support for spatial positioning.

The AudioSource component can play audio files or media streams with options for spatial blending, volume control, looping, and more.

When a page loses visibility (tab becomes inactive), audio will automatically pause unless playInBackground is set to true. On mobile devices, audio always pauses regardless of this setting. When the page becomes visible again, previously playing audio will resume.

AudioSource also responds to application mute state changes. When the application is muted, the volume is set to 0. When unmuted, the volume returns to its previous value.

Hierarchy (View Summary)

Properties

clip gameObject guid playInBackground playOnAwake preload rollOffMode sourceId?

Accessors

activeAndEnabled audioContext context destroyed duration enabled forward isPlaying layer loop maxDistance minDistance name pitch right scene ShouldPlay Sound spatialBlend static tag time time01 up volume worldEuler worldPosition worldQuaternion worldRotation userInteractionRegistered

Methods

addEventListener destroy dispatchEvent earlyUpdate? lateUpdate? onAfterRender? onBeforeRender? onBeforeXR? onCollisionEnter? onCollisionExit? onCollisionStay? onDestroy onEnterXR? onLeaveXR? onPausedChanged? onPointerClick? onPointerDown? onPointerEnter? onPointerExit? onPointerMove? onPointerUp? onTriggerEnter? onTriggerExit? onTriggerStay? onUpdateXR? onValidate? onXRControllerAdded? onXRControllerRemoved? pause play removeEventListener resolveGuids? setWorldPosition setWorldQuaternion setWorldRotation start? startCoroutine stop stopCoroutine supportsXR? registerWaitForAllowAudio

Properties

clip

clip: string | MediaStream = ""

The audio clip to play. Can be a URL string pointing to an audio file or a MediaStream object.

gameObject

gameObject: GameObject

Reference to the GameObject this component is attached to This is a three.js Object3D with additional GameObject functionality

guid

guid: string = "invalid"

Unique identifier for this component instance, used for finding and tracking components

playInBackground

playInBackground: boolean = true

When true, audio will continue playing when the browser tab loses focus. When false, audio will pause when the tab is minimized or not active.

Default

true

playOnAwake

playOnAwake: boolean = false

When true, the audio will automatically start playing when the component is enabled. When false, you must call play() manually to start audio playback.

Default

false

preload

preload: boolean = false

When true, the audio clip will be loaded during initialization rather than when play() is called. This can reduce playback delay but increases initial loading time.

Default

false

rollOffMode

rollOffMode: AudioRolloffMode = 0

Determines how audio volume decreases with distance from the listener.

Default

AudioRolloffMode.Logarithmic

See

AudioRolloffMode

OptionalsourceId

sourceId?: string

Identifier for the source asset that created this component. For example, URL to the glTF file this component was loaded from

Accessors

activeAndEnabled

  • get activeAndEnabled(): boolean

    Checks if this component is currently active (enabled and part of an active GameObject hierarchy) Components that are inactive won't receive lifecycle method calls

    Returns boolean

    True if the component is enabled and all parent GameObjects are active

audioContext

  • get audioContext(): undefined | AudioContext

    Returns the Web Audio API context associated with this audio source.

    Returns undefined | AudioContext

    The AudioContext or null if not available

context

  • get context(): Context

    The context this component belongs to, providing access to the runtime environment including physics, timing utilities, camera, and scene

    Returns Context

  • set context(context: Context): void

    Parameters

    Returns void

destroyed

  • get destroyed(): boolean

    Checks if this component has been destroyed

    Returns boolean

    True if the component or its GameObject has been destroyed

duration

  • get duration(): undefined | number

    The total duration of the current audio clip in seconds.

    Returns undefined | number

    Duration in seconds or undefined if no clip is loaded

enabled

  • get enabled(): boolean

    Controls whether this component is enabled Disabled components don't receive lifecycle callbacks

    Returns boolean

  • set enabled(val: boolean): void

    Parameters

    • val: boolean

    Returns void

forward

  • get forward(): Vector3

    Gets the forward direction vector (0,0,-1) of this component's GameObject in world space

    Returns Vector3

isPlaying

  • get isPlaying(): boolean

    Indicates whether the audio is currently playing.

    Returns boolean

    True if the audio is playing, false otherwise

layer

  • get layer(): number

    The layer value of the GameObject this component is attached to Used for visibility and physics filtering

    Returns number

loop

  • get loop(): boolean

    When true, the audio will repeat after reaching the end. When false, audio will play once and stop.

    Returns boolean

    Default

    false
  • set loop(val: boolean): void

    Parameters

    • val: boolean

    Returns void

maxDistance

  • get maxDistance(): number

    The maximum distance from the audio source beyond which the volume no longer decreases. This defines the outer limit of the attenuation curve.

    Returns number

  • set maxDistance(val: number): void

    Parameters

    • val: number

    Returns void

minDistance

  • get minDistance(): number

    The minimum distance from the audio source at which the volume starts to attenuate. Within this radius, the audio plays at full volume regardless of distance.

    Returns number

  • set minDistance(val: number): void

    Parameters

    • val: number

    Returns void

name

  • get name(): string

    The name of the GameObject this component is attached to Used for debugging and finding objects

    Returns string

  • set name(str: string): void

    Parameters

    • str: string

    Returns void

pitch

  • get pitch(): number

    Returns number

  • set pitch(val: number): void

    Controls the playback rate (speed) of the audio. Values greater than 1 increase speed, values less than 1 decrease it. This affects both speed and pitch of the audio.

    Parameters

    • val: number

    Returns void

    Default

    1

right

  • get right(): Vector3

    Gets the right direction vector (1,0,0) of this component's GameObject in world space

    Returns Vector3

scene

  • get scene(): Scene

    Shorthand accessor for the current scene from the context

    Returns Scene

    The scene this component belongs to

ShouldPlay

  • get ShouldPlay(): boolean

    Indicates whether the audio source is queued to play when possible. This may be true before user interaction has been registered.

    Returns boolean

    Whether the audio source intends to play

Sound

  • get Sound(): null | PositionalAudio

    Returns the underlying PositionalAudio object, creating it if necessary. The audio source needs a user interaction to be initialized due to browser autoplay policies.

    Returns null | PositionalAudio

    The three.js PositionalAudio object or null if unavailable

spatialBlend

  • get spatialBlend(): number

    Controls how the audio is positioned in space. Values range from 0 (2D, non-positional) to 1 (fully 3D positioned). Note: 2D playback is not fully supported in the current implementation.

    Returns number

  • set spatialBlend(val: number): void

    Parameters

    • val: number

    Returns void

static

  • get static(): boolean

    Indicates whether the GameObject is marked as static Static objects typically don't move and can be optimized by the engine

    Returns boolean

  • set static(value: boolean): void

    Parameters

    • value: boolean

    Returns void

tag

  • get tag(): string

    The tag of the GameObject this component is attached to Used for categorizing objects and efficient lookup

    Returns string

  • set tag(str: string): void

    Parameters

    • str: string

    Returns void

time

  • get time(): number

    The current playback position in seconds. Can be set to seek to a specific time in the audio.

    Returns number

  • set time(val: number): void

    Parameters

    • val: number

    Returns void

time01

  • get time01(): number

    The current playback position as a normalized value between 0 and 1. Can be set to seek to a specific position in the audio.

    Returns number

  • set time01(val: number): void

    Parameters

    • val: number

    Returns void

up

  • get up(): Vector3

    Gets the up direction vector (0,1,0) of this component's GameObject in world space

    Returns Vector3

volume

  • get volume(): number

    Controls the overall volume/loudness of the audio. Values range from 0 (silent) to 1 (full volume).

    Returns number

    Default

    1
  • set volume(val: number): void

    Parameters

    • val: number

    Returns void

worldEuler

  • get worldEuler(): Euler

    Gets the rotation of this component's GameObject in world space as Euler angles (in radians)

    Returns Euler

  • set worldEuler(val: Euler): void

    Sets the rotation of this component's GameObject in world space using Euler angles (in radians)

    Parameters

    • val: Euler

      The world rotation Euler angles to set

    Returns void

worldPosition

  • get worldPosition(): Vector3

    Gets the position of this component's GameObject in world space

    Returns Vector3

  • set worldPosition(val: Vector3): void

    Sets the position of this component's GameObject in world space

    Parameters

    • val: Vector3

      The world position vector to set

    Returns void

worldQuaternion

  • get worldQuaternion(): Quaternion

    Gets the rotation of this component's GameObject in world space as a quaternion

    Returns Quaternion

  • set worldQuaternion(val: Quaternion): void

    Sets the rotation of this component's GameObject in world space using a quaternion

    Parameters

    • val: Quaternion

      The world rotation quaternion to set

    Returns void

worldRotation

  • get worldRotation(): Vector3

    Gets the rotation of this component's GameObject in world space as Euler angles (in degrees)

    Returns Vector3

  • set worldRotation(val: Vector3): void

    Sets the rotation of this component's GameObject in world space using Euler angles (in degrees)

    Parameters

    • val: Vector3

      The world rotation vector to set (in degrees)

    Returns void

StaticuserInteractionRegistered

  • get userInteractionRegistered(): boolean

    Checks if the user has interacted with the page to allow audio playback. Audio playback often requires a user gesture first due to browser autoplay policies. This is the same as calling Application.userInteractionRegistered.

    Returns boolean

    Whether user interaction has been registered to allow audio playback

Methods

addEventListener

  • addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void

    Registers an event listener for the specified event type

    Type Parameters

    Parameters

    • type: string

      The event type to listen for

    • listener: (evt: T) => any

      The callback function to execute when the event occurs

    Returns void

destroy

  • destroy(): void

    Destroys this component and removes it from its GameObject After destruction, the component will no longer receive lifecycle callbacks

    Returns void

dispatchEvent

  • dispatchEvent(evt: Event): boolean

    Dispatches an event to all registered listeners

    Parameters

    • evt: Event

      The event object to dispatch

    Returns boolean

    Always returns false (standard implementation of EventTarget)

OptionalearlyUpdate

  • earlyUpdate(): void

    Called at the beginning of each frame before regular updates. Use for logic that needs to run before standard update callbacks.

    Returns void

OptionallateUpdate

  • lateUpdate(): void

    Called after all update functions have been called. Use for calculations that depend on other components being updated first.

    Returns void

OptionalonAfterRender

  • onAfterRender(): void

    Called after the scene has been rendered. Use for post-processing or UI updates that should happen after rendering

    Returns void

OptionalonBeforeRender

  • onBeforeRender(frame: null | XRFrame): void

    Called immediately before the scene is rendered.

    Parameters

    • frame: null | XRFrame

      Current XRFrame if in an XR session, null otherwise

    Returns void

OptionalonBeforeXR

  • onBeforeXR(mode: XRSessionMode, args: XRSessionInit): void

    Called before an XR session is requested Use to modify session initialization parameters

    Parameters

    • mode: XRSessionMode

      The XR session mode being requested

    • args: XRSessionInit

      The session initialization parameters that can be modified

    Returns void

OptionalonCollisionEnter

  • onCollisionEnter(col: Collision): any

    Called when this component's collider begins colliding with another collider.

    Parameters

    • col: Collision

      Information about the collision that occurred

    Returns any

OptionalonCollisionExit

  • onCollisionExit(col: Collision): any

    Called when this component's collider stops colliding with another collider.

    Parameters

    • col: Collision

      Information about the collision that ended

    Returns any

OptionalonCollisionStay

  • onCollisionStay(col: Collision): any

    Called each frame while this component's collider is colliding with another collider

    Parameters

    • col: Collision

      Information about the ongoing collision

    Returns any

onDestroy

  • onDestroy(): void

    Called when the component is destroyed. Use for cleanup operations like removing event listeners

    Returns void

OptionalonEnterXR

OptionalonLeaveXR

OptionalonPausedChanged

  • onPausedChanged(isPaused: boolean, wasPaused: boolean): void

    Called when the context's pause state changes.

    Parameters

    • isPaused: boolean

      Whether the context is currently paused

    • wasPaused: boolean

      The previous pause state

    Returns void

OptionalonPointerClick

OptionalonPointerDown

OptionalonPointerEnter

OptionalonPointerExit

OptionalonPointerMove

OptionalonPointerUp

OptionalonTriggerEnter

  • onTriggerEnter(col: ICollider): any

    Called when this component's trigger collider is entered by another collider

    Parameters

    • col: ICollider

      The collider that entered this trigger

    Returns any

OptionalonTriggerExit

  • onTriggerExit(col: ICollider): any

    Called when another collider exits this component's trigger collider

    Parameters

    • col: ICollider

      The collider that exited this trigger

    Returns any

OptionalonTriggerStay

  • onTriggerStay(col: ICollider): any

    Called each frame while another collider is inside this component's trigger collider

    Parameters

    • col: ICollider

      The collider that is inside this trigger

    Returns any

OptionalonUpdateXR

OptionalonValidate

  • onValidate(prop?: string): void

    Called when a field decorated with @validate() is modified.

    Parameters

    • Optionalprop: string

      The name of the field that was changed

    Returns void

OptionalonXRControllerAdded

OptionalonXRControllerRemoved

pause

  • pause(): void

    Pauses audio playback while maintaining the current position. Use play() to resume from the paused position.

    Returns void

play

  • play(clip?: undefined | string | MediaStream): void

    Plays the audio clip or media stream. If no argument is provided, plays the currently assigned clip.

    Parameters

    Returns void

removeEventListener

  • removeEventListener<T extends Event>(
        type: string,
        listener: (arg: T) => any,
    ): void

    Removes a previously registered event listener

    Type Parameters

    Parameters

    • type: string

      The event type the listener was registered for

    • listener: (arg: T) => any

      The callback function to remove

    Returns void

OptionalresolveGuids

  • resolveGuids(guidsMap: GuidsMap): void

    Called when this component needs to remap guids after an instantiate operation.

    Parameters

    • guidsMap: GuidsMap

      Mapping from old guids to newly generated guids

    Returns void

setWorldPosition

  • setWorldPosition(x: number, y: number, z: number): void

    Sets the position of this component's GameObject in world space using individual coordinates

    Parameters

    • x: number

      X-coordinate in world space

    • y: number

      Y-coordinate in world space

    • z: number

      Z-coordinate in world space

    Returns void

setWorldQuaternion

  • setWorldQuaternion(x: number, y: number, z: number, w: number): void

    Sets the rotation of this component's GameObject in world space using quaternion components

    Parameters

    • x: number

      X component of the quaternion

    • y: number

      Y component of the quaternion

    • z: number

      Z component of the quaternion

    • w: number

      W component of the quaternion

    Returns void

setWorldRotation

  • setWorldRotation(x: number, y: number, z: number, degrees?: boolean): void

    Sets the rotation of this component's GameObject in world space using individual Euler angles

    Parameters

    • x: number

      X-axis rotation

    • y: number

      Y-axis rotation

    • z: number

      Z-axis rotation

    • degrees: boolean = true

      Whether the values are in degrees (true) or radians (false)

    Returns void

Optionalstart

  • start(): void

    Called once at the beginning of the first frame after the component is enabled. Use for initialization that requires other components to be awake.

    Returns void

startCoroutine

  • startCoroutine(routine: Generator, evt?: FrameEvent): Generator

    Starts a coroutine that can yield to wait for events. Coroutines allow for time-based sequencing of operations without blocking. Coroutines are based on generator functions, a JavaScript language feature.

    Parameters

    • routine: Generator

      Generator function to start

    • evt: FrameEvent = FrameEvent.Update

      Event to register the coroutine for (default: FrameEvent.Update)

    Returns Generator

    The generator function that can be used to stop the coroutine

    Example

    Time-based sequencing of operations

    *myCoroutine() {
      yield WaitForSeconds(1); // wait for 1 second
      yield WaitForFrames(10); // wait for 10 frames
      yield new Promise(resolve => setTimeout(resolve, 1000)); // wait for a promise to resolve
    }

    Example

    Coroutine that logs a message every 5 frames

    onEnable() {
      this.startCoroutine(this.myCoroutine());
    }
    private *myCoroutine() {
      while(this.activeAndEnabled) {
        console.log("Hello World", this.context.time.frame);
        // wait for 5 frames
        for(let i = 0; i < 5; i++) yield;
      }
    }

stop

  • stop(): void

    Stops audio playback completely and resets the playback position to the beginning. Unlike pause(), calling play() after stop() will start from the beginning.

    Returns void

stopCoroutine

  • stopCoroutine(routine: Generator, evt?: FrameEvent): void

    Stops a coroutine that was previously started with startCoroutine

    Parameters

    • routine: Generator

      The routine to be stopped

    • evt: FrameEvent = FrameEvent.Update

      The frame event the routine was registered with

    Returns void

OptionalsupportsXR

  • supportsXR(mode: XRSessionMode): boolean

    Determines if this component supports a specific XR mode

    Parameters

    • mode: XRSessionMode

      The XR session mode to check support for

    Returns boolean

    True if the component supports the specified mode

StaticregisterWaitForAllowAudio

  • registerWaitForAllowAudio(cb: Function): void

    Registers a callback that will be executed once the user has interacted with the page, allowing audio playback to begin. This is the same as calling Application.registerWaitForInteraction.

    Parameters

    • cb: Function

      The callback function to execute when user interaction is registered

    Returns void

Settings

Member Visibility

On This Page

Properties
Accessors
Methods