forked from MoonsideGames/FAudioGMS-Docs
287 lines
14 KiB
Markdown
287 lines
14 KiB
Markdown
# 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 | |