The AudioSource can be used to play audio in the scene.
Use clip to set the audio file to play.

Hierarchy (view full)

Properties

clip: string | MediaStream = ""

The audio clip to play. Can be a string (URL) or a MediaStream.

gameObject: GameObject

the object this component is attached to. Note that this is a threejs Object3D with some additional features

guid: string = "invalid"

the unique identifier for this component

playInBackground: boolean = true

When true, the audio will play in the background. This means it will continue playing if the browser tab is not focused/active or minimized

true
playOnAwake: boolean = false

If true, the audio source will start playing as soon as the scene starts. If false, you can call play() to start the audio.

false
preload: boolean = false

If true, the audio source will start loading the audio clip as soon as the scene starts. If false, the audio clip will be loaded when play() is called.

false
sourceId?: string

holds the source identifier this object was created with/from (e.g. if it was part of a glTF file the sourceId holds the url to the glTF)

Accessors

  • get activeAndEnabled(): boolean
  • Returns boolean

    true if the object is enabled and active in the hierarchy

  • get context(): Context
  • Use the context to get access to many Needle Engine features and use physics, timing, access the camera or scene

    Returns Context

  • set context(context): void
  • Parameters

    Returns void

  • get destroyed(): boolean
  • Returns boolean

    true if this component was destroyed (this.destroy()) or the whole object this component was part of

  • get duration(): undefined | number
  • The duration of the audio clip in seconds.

    Returns undefined | number

  • get enabled(): boolean
  • Returns boolean

  • set enabled(val): void
  • Parameters

    • val: boolean

    Returns void

  • get forward(): Vector3
  • Forward (0,0,-1) vector in world space

    Returns Vector3

  • get hideFlags(): HideFlags
  • Returns HideFlags

  • get isPlaying(): boolean
  • If true, the audio is currently playing.

    Returns boolean

  • get layer(): number
  • Returns number

    the layer of the gameObject this component is attached to

  • get loop(): boolean
  • If true, the audio source will loop the audio clip. If false, the audio clip will play once.

    Returns boolean

    false
    
  • set loop(val): void
  • Parameters

    • val: boolean

    Returns void

  • get maxDistance(): number
  • Returns number

  • set maxDistance(val): void
  • Parameters

    • val: number

    Returns void

  • get minDistance(): number
  • Returns number

  • set minDistance(val): void
  • Parameters

    • val: number

    Returns void

  • get name(): string
  • Returns string

    the name of the gameObject this component is attached to

  • set name(str): void
  • Parameters

    • str: string

    Returns void

  • get pitch(): number
  • Returns number

  • set pitch(val): void
  • Parameters

    • val: number

    Returns void

  • get right(): Vector3
  • Right (1,0,0) vector in world space

    Returns Vector3

  • get scene(): Scene
  • shorthand for this.context.scene

    Returns Scene

    the scene of the context

  • get ShouldPlay(): boolean
  • Returns boolean

  • get Sound(): null | PositionalAudio
  • Returns null | PositionalAudio

  • get spatialBlend(): number
  • Can be used to play the audio clip in 2D or 3D space.
    2D Playback is currently not fully supported.
    0 = 2D, 1 = 3D

    Returns number

  • set spatialBlend(val): void
  • Parameters

    • val: number

    Returns void

  • get static(): boolean
  • Is the gameObject marked as static

    Returns boolean

  • set static(value): void
  • Parameters

    • value: boolean

    Returns void

  • get tag(): string
  • Returns string

    the tag of the gameObject this component is attached to

  • set tag(str): void
  • Parameters

    • str: string

    Returns void

  • get time(): number
  • The current time of the audio clip in seconds.

    Returns number

  • set time(val): void
  • Parameters

    • val: number

    Returns void

  • get time01(): number
  • The current time of the audio clip in 0-1 range.

    Returns number

  • set time01(val): void
  • Parameters

    • val: number

    Returns void

  • get up(): Vector3
  • Up (0,1,0) vector in world space

    Returns Vector3

  • get volume(): number
  • Returns number

  • set volume(val): void
  • Parameters

    • val: number

    Returns void

  • get worldEuler(): Euler
  • Returns Euler

  • set worldEuler(val): void
  • Parameters

    Returns void

  • get worldPosition(): Vector3
  • Returns Vector3

  • set worldPosition(val): void
  • Parameters

    Returns void

  • get worldQuaternion(): Quaternion
  • Returns Quaternion

  • set worldQuaternion(val): void
  • Parameters

    Returns void

  • get worldRotation(): Vector3
  • Returns Vector3

  • set worldRotation(val): void
  • Parameters

    Returns void

Methods

  • Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

    The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

    When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

    When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

    When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

    If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

    The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: ((evt: T) => any)
        • (evt): any
        • Parameters

          • evt: T

          Returns any

    Returns void

  • Destroys this component (and removes it from the object)

    Returns void

  • Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    MDN Reference

    Parameters

    Returns boolean

  • first callback in a frame (called every frame when implemented)

    Returns void

  • late callback in a frame (called every frame when implemented)

    Returns void

  • called before the scene gets rendered in the main update loop

    Parameters

    • frame: null | XRFrame

    Returns void

  • Called before the XR session is requested. Use this callback if you want to modify the session init features

    Parameters

    • mode: XRSessionMode
    • args: XRSessionInit

    Returns void

  • Called when the component gets destroyed

    Returns void

  • Callback when this component joins a xr session (or becomes active in a running XR session)

    Parameters

    Returns void

  • Callback when this component exists a xr session (or when it becomes inactive in a running XR session)

    Parameters

    Returns void

  • Called for all scripts when the context gets paused or unpaused

    Parameters

    • isPaused: boolean
    • wasPaused: boolean

    Returns void

  • Called when an object (or any child object) is clicked (needs a EventSystem in the scene)

    Parameters

    Returns any

  • Called when a pointer (mouse, touch, xr controller) starts pointing on/hovering an object (or a child object)

    Parameters

    Returns any

  • Called when a pointer (mouse, touch, xr controller) exists an object (it was hovering the object before but now it's not anymore)

    Parameters

    Returns any

  • Called when a pointer (mouse, touch, xr controller) is moving over an object (or a child object)

    Parameters

    Returns any

  • Called when a button is released (which was previously pressed in onPointerDown)

    Parameters

    Returns any

  • called when you decorate fields with the @validate() decorator

    Parameters

    • Optionalprop: string

      the name of the field that was changed

    Returns void

  • Callback when a controller is connected/added while in a XR session
    OR when the component joins a running XR session that has already connected controllers
    OR when the component becomes active during a running XR session that has already connected controllers

    Returns void

  • Pause the audio

    Returns void

  • Play a audioclip or mediastream

    Parameters

    Returns void

  • Removes the event listener in target's event listener list with the same type, callback, and options.

    MDN Reference

    Type Parameters

    Parameters

    • type: string
    • listener: ((arg: T) => any)
        • (arg): any
        • Parameters

          • arg: T

          Returns any

    Returns void

  • called on a component with a map of old to new guids (e.g. when instantiate generated new guids and e.g. timeline track bindings needs to remape them)

    Parameters

    • guidsMap: GuidsMap

    Returns void

  • Parameters

    • x: number
    • y: number
    • z: number
    • w: number

    Returns void

  • Parameters

    • x: number
    • y: number
    • z: number
    • degrees: boolean = true

    Returns void

  • called at the beginning of a frame (once per component)

    Returns void

  • starts a coroutine (javascript generator function)
    yield will wait for the next frame:

    • Use yield WaitForSeconds(1) to wait for 1 second.
    • Use yield WaitForFrames(10) to wait for 10 frames.
    • Use yield new Promise(...) to wait for a promise to resolve.

    Parameters

    • routine: Generator<unknown, any, unknown>

      generator function to start

    • evt: FrameEvent = FrameEvent.Update

      event to register the coroutine for (default: FrameEvent.Update). Note that all coroutine FrameEvent callbacks are invoked after the matching regular component callbacks. For example FrameEvent.Update will be called after regular component update() methods)

    Returns Generator<unknown, any, unknown>

    the generator function (use it to stop the coroutine with stopCoroutine)

    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 the audio and reset the time to 0

    Returns void

  • Stop a coroutine that was previously started with startCoroutine

    Parameters

    • routine: Generator<unknown, any, unknown>

      the routine to be stopped

    • evt: FrameEvent = FrameEvent.Update

      the frame event to unregister the routine from (default: FrameEvent.Update)

    Returns void

  • Optional callback, you can implement this to only get callbacks for VR or AR sessions if necessary.

    Parameters

    • mode: XRSessionMode

    Returns boolean

    true if the mode is supported (if false the mode is not supported by this component and it will not receive XR callbacks for this mode)

  • Register a callback that is called when the user has interacted with the page to allow audio playback. Internally calling Application.registerWaitForInteraction

    Parameters

    Returns void