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

287 lines
14 KiB
Markdown
Raw Normal View History

2021-11-02 22:41:02 +00:00
# Sound Instances
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Play(soundInstanceID, loop)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
2021-11-02 22:30:43 +00:00
|-----------------|--------|--------------------------------------------------------------------------------|
|`soundInstanceID`|number |Sound instance to target |
|`loop` |boolean |Whether the sound instance should replay from the start when it finishes playing|
2021-11-02 23:42:12 +00:00
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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Pause(soundInstanceID)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
Pauses playback of a sound instance. It can later be resumed by calling `FAudio_SoundInstance_Resume(soundInstanceID)`.
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Stop(soundInstanceID)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
Stops playback of the given sound instance completely. To restart playback, `FAudio_SoundInstance_Play()` should be called.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Destroy(soundInstanceID)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
Destroys a sound instance, freeing memory associated with it.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_DestroyWhenFinished(soundInstanceID)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetPan(soundInstanceID, pan)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|---------------------------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
2021-11-02 21:13:56 +00:00
|`pan` |number |Should be from `-1` (100% left) to `+1` (100% right) with `0` being central|
2021-11-02 22:30:43 +00:00
Sets the stereo (left/right) panning of the sound instance. This is useful to fake positional audio in 2D, amongst other mixing techniques.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetPitch(soundInstanceID, pitch)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
2021-11-02 21:13:56 +00:00
|`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|
2021-11-02 22:30:43 +00:00
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).
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetVolume(soundInstanceID, volume)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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()`.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Set3DPosition(soundInstanceID, x, y, z)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_Set3DVelocity(soundInstanceID, xVelocity, yVelocity, zVelocity)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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).
2021-11-02 21:13:56 +00:00
 
2022-01-26 19:20:47 +00:00
## `~_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.
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetTrackPositionInSeconds(soundInstanceID, trackPositionInSeconds)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|------------------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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.
2021-11-02 21:13:56 +00:00
 
2021-11-03 02:46:48 +00:00
## `~_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.
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetVolumeOverTime(soundInstanceID, volume, milliseconds)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetLowPassFilter(soundInstanceID, lowPassFilter, Q)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
2021-11-02 22:30:43 +00:00
|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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetHighPassFilter(soundInstanceID, lowPassFilter, Q)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
2021-11-02 22:30:43 +00:00
|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` |
2021-11-02 21:13:56 +00:00
2021-11-02 22:30:43 +00:00
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.
2021-11-02 21:13:56 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_SetBandPassFilter(soundInstanceID, bandPassFilter, Q)`
2021-11-02 21:13:56 +00:00
**Returns:** N/A (`undefined`)
2021-11-02 22:30:43 +00:00
|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.
2021-11-02 21:13:56 +00:00
2021-11-02 21:20:20 +00:00
 
2022-01-26 19:20:47 +00:00
## `~_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`.
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_GetPitch(soundInstanceID)`
2021-11-02 21:20:20 +00:00
**Returns:** Number, the pitch of the sound instance, with `1` being no pitch shift
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
2021-11-02 21:20:20 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_GetVolume(soundInstanceID)`
2021-11-02 21:20:20 +00:00
**Returns:** Number, the volume of the sound instance, from `0` (inaudible) to `1` (full volume)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
2021-11-02 21:20:20 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_GetTrackLengthInSeconds(soundInstanceID)`
2021-11-02 21:20:20 +00:00
**Returns:** Number, the track length (in seconds)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |
2021-11-02 21:20:20 +00:00
 
2021-11-02 21:45:21 +00:00
## `~_SoundInstance_GetTrackPositionInSeconds(soundInstanceID)`
2021-11-02 21:20:20 +00:00
**Returns:** Number, the track position (in seconds)
|Argument |Datatype|Description |
|-----------------|--------|--------------------------------------------------------|
2021-11-02 22:30:43 +00:00
|`soundInstanceID`|number |Sound instance to target |