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