# SoundInstance3d

Class · extends [`SoundInstance`](https://api.playcanvas.com/engine/classes/SoundInstance.md) · category: Sound

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/platform/sound/instance3d.js#L26

A SoundInstance3d plays a [Sound](https://api.playcanvas.com/engine/classes/Sound.md) in 3D.

It is what a positional [SoundComponent](https://api.playcanvas.com/engine/classes/SoundComponent.md) creates. The sound is placed at [position](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#position)
and its volume falls off with distance from the [AudioListenerComponent](https://api.playcanvas.com/engine/classes/AudioListenerComponent.md) according to
[distanceModel](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#distancemodel), one of [DISTANCE_LINEAR](https://api.playcanvas.com/engine/variables/DISTANCE_LINEAR.md), [DISTANCE_INVERSE](https://api.playcanvas.com/engine/variables/DISTANCE_INVERSE.md) and
[DISTANCE_EXPONENTIAL](https://api.playcanvas.com/engine/variables/DISTANCE_EXPONENTIAL.md), shaped by [refDistance](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#refdistance), [maxDistance](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#maxdistance) and
[rollOffFactor](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#rollofffactor). The owning slot keeps [position](https://api.playcanvas.com/engine/classes/SoundInstance3d.md#position) in step with its entity, so these
properties are usually set on the component rather than on each instance.

## Constructors

### constructor

```ts
new SoundInstance3d(manager: SoundManager, sound: Sound, options?: object)
```

Create a new SoundInstance3d instance.

**Parameters**

- `manager` ([`SoundManager`](https://api.playcanvas.com/engine/classes/SoundManager.md)): The sound manager.
- `sound` ([`Sound`](https://api.playcanvas.com/engine/classes/Sound.md)): The sound to play.
- `options` (`object`, optional, default `{}`): Options for the instance.
    - `options.distanceModel` (`string`, optional): Determines which algorithm to use to reduce the
      volume of the audio as it moves away from the listener. Can be:

      - [DISTANCE_LINEAR](https://api.playcanvas.com/engine/variables/DISTANCE_LINEAR.md)
      - [DISTANCE_INVERSE](https://api.playcanvas.com/engine/variables/DISTANCE_INVERSE.md)
      - [DISTANCE_EXPONENTIAL](https://api.playcanvas.com/engine/variables/DISTANCE_EXPONENTIAL.md)

      Defaults to [DISTANCE_LINEAR](https://api.playcanvas.com/engine/variables/DISTANCE_LINEAR.md).
    - `options.duration` (`number`, optional): The total time after the startTime when playback will
      stop or restart if loop is true.
    - `options.loop` (`boolean`, optional): Whether the sound should loop when it reaches the end or
      not. Defaults to false.
    - `options.maxDistance` (`number`, optional): The maximum distance from the listener at which
      audio falloff stops. Note the volume of the audio is not 0 after this distance, but just
      doesn't fall off anymore. Defaults to 10000.
    - `options.pitch` (`number`, optional): The relative pitch. Defaults to 1 (plays at normal pitch).
    - `options.position` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): The position of the sound in 3D space.
    - `options.refDistance` (`number`, optional): The reference distance for reducing volume as the
      sound source moves further from the listener. Defaults to 1.
    - `options.rollOffFactor` (`number`, optional): The factor used in the falloff equation. Defaults
      to 1.
    - `options.startTime` (`number`, optional): The time from which the playback will start. Default
      is 0 to start at the beginning.
    - `options.volume` (`number`, optional): The playback volume, between 0 and 1. Defaults to 1.

## Accessors

### distanceModel

```ts
get distanceModel(): string
set distanceModel(value: string)
```

Gets which algorithm to use to reduce the volume of the audio as it moves away from
the listener.

### maxDistance

```ts
get maxDistance(): number
set maxDistance(value: number)
```

Gets the maximum distance from the listener at which audio falloff stops.

### position

```ts
get position(): Vec3
set position(value: Vec3)
```

Gets the position of the sound in 3D space.

### refDistance

```ts
get refDistance(): number
set refDistance(value: number)
```

Gets the reference distance for reducing volume as the sound source moves further from the
listener.

### rollOffFactor

```ts
get rollOffFactor(): number
set rollOffFactor(value: number)
```

Gets the factor used in the falloff equation.

## Inherited from [SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md)

- `source: AudioBufferSourceNode | null = null`
- `get currentTime(): number` · `set currentTime(value: number)`
- `get duration(): number` · `set duration(value: number)`
- `get isPaused(): boolean`
- `get isPlaying(): boolean`
- `get isStopped(): boolean`
- `get isSuspended(): boolean`
- `get loop(): boolean` · `set loop(value: boolean)`
- `get pitch(): number` · `set pitch(pitch: number)`
- `get sound(): Sound` · `set sound(value: Sound)`
- `get startTime(): number` · `set startTime(value: number)`
- `get volume(): number` · `set volume(volume: number)`
- `clearExternalNodes(): void`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `getExternalNodes(): AudioNode[]`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `pause(): boolean`
- `play(): boolean`
- `resume(): boolean`
- `setExternalNodes(firstNode: AudioNode, lastNode?: AudioNode): void`
- `stop(): boolean`
- `static EVENT_END: string = 'end'`
- `static EVENT_PAUSE: string = 'pause'`
- `static EVENT_PLAY: string = 'play'`
- `static EVENT_RESUME: string = 'resume'`
- `static EVENT_STOP: string = 'stop'`