# SoundComponent

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

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/components/sound/component.js#L56

The SoundComponent enables an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) to play audio. The SoundComponent can manage
multiple [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md)s, each of which can play a different audio asset with its own set
of properties such as volume, pitch, and looping behavior.

The SoundComponent supports positional audio, meaning that the sound can be played relative
to the Entity's position in 3D space. This is useful for creating immersive audio experiences
where the sound's volume and panning are affected by the listener's position and orientation.
Positional audio requires that an Entity with an [AudioListenerComponent](https://api.playcanvas.com/engine/classes/AudioListenerComponent.md) be added to the
scene.

You should never need to use the SoundComponent constructor directly. To add a SoundComponent
to an Entity, use [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent):

```javascript
const entity = new Entity();
entity.addComponent('sound', {
    volume: 0.8,
    positional: true
});
```

Once the SoundComponent is added to the entity, you can access it via the [Entity#sound](https://api.playcanvas.com/engine/classes/Entity.md#sound)
property:

```javascript
entity.sound.volume = 0.9;  // Set the volume for all sounds

console.log(entity.sound.volume); // Get the volume and print it
```

Add individual sounds by creating sound slots on the component:

```javascript
entity.sound.addSlot('beep', {
    asset: asset
});
```

Relevant Engine API examples:

- [Positional Sound](https://playcanvas.github.io/#/sound/positional)

## Accessors

### distanceModel

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

Gets which algorithm to use to reduce the volume of the sound 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.

### pitch

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

Gets the pitch modifier to play the audio with.

### positional

```ts
get positional(): boolean
set positional(newValue: boolean)
```

Gets whether the component plays positional sound.

### 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.

### slots

```ts
get slots(): Readonly<Record<string, SoundSlot>>
set slots(newValue: Readonly<Record<string, SoundSlot>>)
```

Gets a dictionary that contains the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md)s managed by this SoundComponent. Use
addSlot and removeSlot to change slots.

### volume

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

Gets the volume modifier to play the audio with.

## Methods

### addSlot

```ts
addSlot(name: string, options?: object): SoundSlot | null
```

Creates a new [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) with the specified name.

**Parameters**

- `name` (`string`): The name of the slot.
- `options` (`object`, optional): Settings for the slot.
    - `options.asset` (`number`, optional): The asset id of the audio asset that is going to be played
      by this slot.
    - `options.autoPlay` (`boolean`, optional): If true, the slot will start playing as soon as its
      audio asset is loaded. Defaults to false.
    - `options.duration` (`number`, optional): The duration of the sound that the slot will play
      starting from startTime. Defaults to `null` which means play to end of the sound.
    - `options.loop` (`boolean`, optional): If true, the sound will restart when it reaches the end.
      Defaults to false.
    - `options.overlap` (`boolean`, optional): If true, then sounds played from slot will be played
      independently of each other. Otherwise the slot will first stop the current sound before
      starting the new one. Defaults to false.
    - `options.pitch` (`number`, optional): The relative pitch. Defaults to 1 (plays at normal pitch).
    - `options.startTime` (`number`, optional): The start time from which the sound will start playing.
      Defaults to 0 to start at the beginning.
    - `options.volume` (`number`, optional): The playback volume, between 0 and 1. Defaults to 1.

**Returns** [`SoundSlot`](https://api.playcanvas.com/engine/classes/SoundSlot.md) `| null`: The new slot or null if the slot already exists.

**Example**

```ts
// get an asset by id
const asset = app.assets.get(10);
// add a slot
this.entity.sound.addSlot('beep', {
    asset: asset
});
// play
this.entity.sound.play('beep');
```

### isLoaded

```ts
isLoaded(name: string): boolean
```

Returns true if the asset of the slot with the specified name is loaded..

**Parameters**

- `name` (`string`): The name of the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) to look for.

**Returns** `boolean`: True if the slot with the specified name exists and its asset is loaded.

### isPaused

```ts
isPaused(name: string): boolean
```

Returns true if the slot with the specified name is currently paused.

**Parameters**

- `name` (`string`): The name of the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) to look for.

**Returns** `boolean`: True if the slot with the specified name exists and is currently paused.

### isPlaying

```ts
isPlaying(name: string): boolean
```

Returns true if the slot with the specified name is currently playing.

**Parameters**

- `name` (`string`): The name of the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) to look for.

**Returns** `boolean`: True if the slot with the specified name exists and is currently playing.

### isStopped

```ts
isStopped(name: string): boolean
```

Returns true if the slot with the specified name is currently stopped.

**Parameters**

- `name` (`string`): The name of the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) to look for.

**Returns** `boolean`: True if the slot with the specified name exists and is currently stopped.

### pause

```ts
pause(name?: string): void
```

Pauses playback of the slot with the specified name. If the name is undefined then all slots
currently played will be paused. The slots can be resumed by calling [resume](https://api.playcanvas.com/engine/classes/SoundComponent.md#resume).

**Parameters**

- `name` (`string`, optional): The name of the slot to pause. Leave undefined to pause everything.

**Example**

```ts
// pause all sounds
this.entity.sound.pause();
// pause a specific sound
this.entity.sound.pause('beep');
```

### play

```ts
play(name: string): SoundInstance | null
```

Begins playing the sound slot with the specified name. The slot will restart playing if it
is already playing unless the overlap field is true in which case a new sound will be
created and played.

**Parameters**

- `name` (`string`): The name of the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) to play.

**Returns** [`SoundInstance`](https://api.playcanvas.com/engine/classes/SoundInstance.md) `| null`: The sound instance that will be played. Returns null if the
component or its parent entity is disabled or if the SoundComponent has no slot with the
specified name.

**Example**

```ts
// get asset by id
const asset = app.assets.get(10);
// create a slot and play it
this.entity.sound.addSlot('beep', {
    asset: asset
});
this.entity.sound.play('beep');
```

### removeSlot

```ts
removeSlot(name: string): void
```

Removes the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) with the specified name.

**Parameters**

- `name` (`string`): The name of the slot.

**Example**

```ts
// remove a slot called 'beep'
this.entity.sound.removeSlot('beep');
```

### resume

```ts
resume(name?: string): void
```

Resumes playback of the sound slot with the specified name if it's paused. If no name is
specified all slots will be resumed.

**Parameters**

- `name` (`string`, optional): The name of the slot to resume. Leave undefined to resume everything.

**Example**

```ts
// resume all sounds
this.entity.sound.resume();
// resume a specific sound
this.entity.sound.resume('beep');
```

### slot

```ts
slot(name: string): SoundSlot | undefined
```

Returns the slot with the specified name.

**Parameters**

- `name` (`string`): The name of the slot.

**Returns** [`SoundSlot`](https://api.playcanvas.com/engine/classes/SoundSlot.md) `| undefined`: The slot.

**Example**

```ts
// get a slot and set its volume
this.entity.sound.slot('beep').volume = 0.5;
```

### stop

```ts
stop(name?: string): void
```

Stops playback of the sound slot with the specified name if it's paused. If no name is
specified all slots will be stopped.

**Parameters**

- `name` (`string`, optional): The name of the slot to stop. Leave undefined to stop everything.

**Example**

```ts
// stop all sounds
this.entity.sound.stop();
// stop a specific sound
this.entity.sound.stop('beep');
```

## Events

### EVENT_END

```ts
static EVENT_END: string = 'end'
```

Fired when a sound instance stops playing because it reached its end. The handler is passed
the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) and the [SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md) that ended.

**Example**

```ts
entity.sound.on('end', (slot, instance) => {
    console.log(`Sound ${slot.name} ended`);
});
```

### EVENT_PAUSE

```ts
static EVENT_PAUSE: string = 'pause'
```

Fired when a sound instance is paused. The handler is passed the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) and the
[SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md) that was paused.

**Example**

```ts
entity.sound.on('pause', (slot, instance) => {
    console.log(`Sound ${slot.name} paused`);
});
```

### EVENT_PLAY

```ts
static EVENT_PLAY: string = 'play'
```

Fired when a sound instance starts playing. The handler is passed the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) and
the [SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md) that started playing.

**Example**

```ts
entity.sound.on('play', (slot, instance) => {
    console.log(`Sound ${slot.name} started playing`);
});
```

### EVENT_RESUME

```ts
static EVENT_RESUME: string = 'resume'
```

Fired when a sound instance is resumed. The handler is passed the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) and the
[SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md) that was resumed.

**Example**

```ts
entity.sound.on('resume', (slot, instance) => {
    console.log(`Sound ${slot.name} resumed`);
});
```

### EVENT_STOP

```ts
static EVENT_STOP: string = 'stop'
```

Fired when a sound instance is stopped. The handler is passed the [SoundSlot](https://api.playcanvas.com/engine/classes/SoundSlot.md) and the
[SoundInstance](https://api.playcanvas.com/engine/classes/SoundInstance.md) that was stopped.

**Example**

```ts
entity.sound.on('stop', (slot, instance) => {
    console.log(`Sound ${slot.name} stopped`);
});
```

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

- `entity: Entity`
- `system: ComponentSystem`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `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`