FAudioGMS-Docs/docs/latest/Functions-(Sound-Instances).md

# Sound Instances

## `~_SoundInstance_Play(soundInstanceID, loop)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                           |
|-----------------|--------|--------------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                        |
|`loop`           |boolean |Whether the sound instance should replay from the start when it finishes playing|

Plays the given sound instance.

?> Note that once playback is complete the sound instance will not automatically be destroyed unless FAudioGMS_SoundInstance_DestroyWhenFinished is used.

 

## `~_SoundInstance_Pause(soundInstanceID)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                           |
|-----------------|--------|------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                              |

Pauses playback of a sound instance. It can later be resumed by calling `FAudio_SoundInstance_Resume(soundInstanceID)`.

 

## `~_SoundInstance_Stop(soundInstanceID)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                           |
|-----------------|--------|------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                              |

Stops playback of the given sound instance completely. To restart playback, `FAudio_SoundInstance_Play()` should be called.

 

## `~_SoundInstance_Destroy(soundInstanceID)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                           |
|-----------------|--------|------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                              |

Destroys a sound instance, freeing memory associated with it.

 

## `~_SoundInstance_DestroyWhenFinished(soundInstanceID)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                           |
|-----------------|--------|------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                              |

Sets a sound instance to self-destruct when it finishes playing. This is useful for one-off audio clips that you don't want to keep track of.

 

## `~_SoundInstance_SetPan(soundInstanceID, pan)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                                |
|-----------------|--------|---------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                   |
|`pan`            |number  |Should be from `-1` (100% left) to `+1` (100% right) with `0` being central|

Sets the stereo (left/right) panning of the sound instance. This is useful to fake positional audio in 2D, amongst other mixing techniques.

 

## `~_SoundInstance_SetPitch(soundInstanceID, pitch)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                                                                                                                 |
|-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                                                                                                    |
|`pitch`          |number  |Frequency multiplier. A value of `2` will double the frequency and make the pitch higher, a value of `0.5` will halve the frequency and make the pitch lower|

Changes the pitch of the audio by time-stretching or time-condensing playback. This also changes the playback time accordingly (a higher-pitched sound will take less time to fully play).

 

## `~_SoundInstance_SetVolume(soundInstanceID, volume)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |
|`volume`         |number  |Volume of the sound instance. `1` is 100% volume        |

Sets the volume for the sound instance. To change volume smoothly over time, please use `FAudio_SoundInstance_SetVolumeOverTime()`.

 

## `~_SoundInstance_Set3DPosition(soundInstanceID, x, y, z)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |
|`x`              |number  |x-position of the sound instance                        |
|`y`              |number  |y-position of the sound instance                        |
|`z`              |number  |z-position of the sound instance                        |

Places the sound instance in 3D space. In combination with `FAudio_SetListenerPosition()`, this sets the relative panning and volume for the sound instance to give the illusion of the player being in a 3D environment.

 

## `~_SoundInstance_Set3DVelocity(soundInstanceID, xVelocity, yVelocity, zVelocity)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |
|`xVelocity`      |number  |x-component of the velocity of the sound instance       |
|`yVelocity`      |number  |y-component of the velocity of the sound instance       |
|`zVelocity`      |number  |z-component of the velocity of the sound instance       |

Sets the velocity of the sound instance, allowing for pitch shifting to emulate the [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect).

 

## `~_SoundInstance_Set3DOrientation(soundInstanceID, xFront, yFront, zFront, xTop, yTop, zTop)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                      |
|-----------------|--------|-----------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                         |
|`xFront`         |number  |x-component of the front orientation vector of the sound instance|
|`yFront`         |number  |y-component of the front orientation vector of the sound instance|
|`zFront`         |number  |z-component of the front orientation vector of the sound instance|
|`xTop`           |number  |x-component of the top orientation vector of the sound instance  |
|`yTop`           |number  |y-component of the top orientation vector of the sound instance  |
|`zTop`           |number  |z-component of the top orientation vector of the sound instance  |

Sets the 3D orientation of the sound instance expressed as front and top vectors.

 

## `~_SoundInstance_SetTrackPositionInSeconds(soundInstanceID, trackPositionInSeconds)`

**Returns:** N/A (`undefined`)

|Argument                |Datatype|Description                                             |
|------------------------|--------|--------------------------------------------------------|
|`soundInstanceID`       |number  |Sound instance to target                                |
|`trackPositionInSeconds`|number  |Track position to jump to, in seconds                   |

Jumps to a fixed position in the sound instance's audio asset. This is useful for audio assets that are comprised of a few different sections.

 

## `~_SoundInstance_SetLoopPoints(soundInstanceID, loopStartInMilliseconds, loopEndInMilliseconds)`

**Returns:** N/A (`undefined`)

|Argument                |Datatype|Description                                             |
|------------------------|--------|--------------------------------------------------------|
|`soundInstanceID`       	|number  |Sound instance to target                                |
|`loopStartInMilliseconds`	|number  |Start of the loop, in milliseconds 	|
|`loopEndInMilliseconds`	|number  |End of the loop, in milliseconds 	|

Loops over a specific region of the sound instance. This is useful for dynamic audio.

!> This function must be called BEFORE calling `FAudioGMS_SoundInstance_Play` or it will not behave as you expect.

 

## `~_SoundInstance_SetVolumeOverTime(soundInstanceID, volume, milliseconds)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |
|`volume`         |number  |Target velocity to interpolate towards                  |
|`milliseconds`   |number  |Duration of the interpolation, in milliseconds          |

Smoothly interpolates the volume of a sound instance over time. This time can be very short or very long, as you see fit.

 

## `~_SoundInstance_SetLowPassFilter(soundInstanceID, lowPassFilter, Q)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                              |
|-----------------|--------|-------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                 |
|`lowPassFilter`  |number  |Frequency of the low-pass. This is a value from `0` (20hz) to `1` (20khz)|
|`Q`              |number  |Unitless - the steepness of the cutoff knee. A recommended value is `1`  |

Sets a low-pass filter on a sound instance, cutting out high frequencies. This has the effect of making the sound seem muffled.

 

## `~_SoundInstance_SetHighPassFilter(soundInstanceID, lowPassFilter, Q)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                               |
|-----------------|--------|--------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                  |
|`highPassFilter` |number  |Frequency of the high-pass. This is a value from `0` (20hz) to `1` (20khz)|
|`Q`              |number  |Unitless - the steepness of the cutoff knee. A recommended value is `1`   |

Sets a high-pass filter on a sound instance, cutting out low frequencies. This has the effect of making the sound seem tinny and thin.

 

## `~_SoundInstance_SetBandPassFilter(soundInstanceID, bandPassFilter, Q)`

**Returns:** N/A (`undefined`)

|Argument         |Datatype|Description                                                               |
|-----------------|--------|--------------------------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                                  |
|`bandPassFilter` |number  |Frequency of the band-pass. This is a value from `0` (20hz) to `1` (20khz)|
|`Q`              |number  |Unitless - the steepness of the cutoff knee. A recommended value is `1`   |

Sets a band-pass filter on a sound instance, cutting out frequencies above and below the center of the band. What this sounds like depends on what frequency you choose, but it has a habit of making sounds seem nasal and boxy.

 

## `~_SoundInstance_QueueSoundInstance(soundInstanceID, queueSoundInstanceID)`

**Returns:** N/A (`undefined`)

|Argument              |Datatype|Description                                                               |
|----------------------|--------|--------------------------------------------------------------------------|
|`soundInstanceID`     |number  |Sound instance to target                                                  |
|`queueSoundInstanceID`|number  |Sound instance to queue                                                   |

Queues a `queueSoundInstanceID` sound instance to play after the `soundInstanceID`.

 

## `~_SoundInstance_GetPitch(soundInstanceID)`

**Returns:** Number, the pitch of the sound instance, with `1` being no pitch shift

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |

 

## `~_SoundInstance_GetVolume(soundInstanceID)`

**Returns:** Number, the volume of the sound instance, from `0` (inaudible) to `1` (full volume)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |

 

## `~_SoundInstance_GetTrackLengthInSeconds(soundInstanceID)`

**Returns:** Number, the track length (in seconds)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |

 

## `~_SoundInstance_GetTrackPositionInSeconds(soundInstanceID)`

**Returns:** Number, the track position (in seconds)

|Argument         |Datatype|Description                                             |
|-----------------|--------|--------------------------------------------------------|
|`soundInstanceID`|number  |Sound instance to target                                |