# 7. Core API Reference | Sound

Container for sample data that can be played on a Channel.

Create with System::createSound or System::createStream.

Format information:

- Sound::getName Retrieves the name of a sound.
- Sound::getFormat Returns format information about the sound.
- Sound::getLength Retrieves the length using the specified time unit.
- Sound::getNumTags Retrieves the number of metadata tags.
- Sound::getTag Retrieves a metadata tag.

- FMOD_TAG Tag data / metadata description.

- FMOD_SOUND_TYPE Recognized audio formats that can be loaded into a Sound.
- FMOD_SOUND_FORMAT These definitions describe the native format of the hardware or software buffer that will be used.
- FMOD_TAGTYPE List of tag data / metadata types that could be stored within a sound. These include id3 tags, metadata from netstreams and vorbis/asf data.
- FMOD_TAGDATATYPE List of tag data / metadata types.

Defaults when played:

- Sound::set3DConeSettings Sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.
- Sound::get3DConeSettings Retrieves the inside and outside angles of the 3D projection cone and the outside volume.
- Sound::set3DCustomRolloff Sets a custom rolloff shape for 3D distance attenuation.
- Sound::get3DCustomRolloff Retrieves the current custom rolloff shape for 3D distance attenuation.
- Sound::set3DMinMaxDistance Sets the minimum and maximum audible distance for a 3D sound.
- Sound::get3DMinMaxDistance Retrieve the minimum and maximum audible distance for a 3D sound.
- Sound::setDefaults Sets a sound's default playback attributes.
- Sound::getDefaults Retrieves a sound's default playback attributes.
- Sound::setMode Sets or alters the mode of a sound.
- Sound::getMode Retrieves the mode of a sound.
- Sound::setLoopCount Sets the sound to loop a specified number of times before stopping if the playback mode is set to looping.
- Sound::getLoopCount Retrieves the sound's loop count.
- Sound::setLoopPoints Sets the loop points within a sound.
- Sound::getLoopPoints Retrieves the loop points for a sound.

Relationship management:

- Sound::setSoundGroup Moves the sound from its existing SoundGroup to the specified sound group.
- Sound::getSoundGroup Retrieves the sound's current sound group.
- Sound::getNumSubSounds Retrieves the number of subsounds stored within a sound.
- Sound::getSubSound Retrieves a handle to a Sound object that is contained within the parent sound.
- Sound::getSubSoundParent Retrieves the parent Sound object that contains this subsound.

Data reading:

- Sound::getOpenState Retrieves the state a sound is in after being opened with the non blocking flag, or the current state of the streaming buffer.
- Sound::readData Reads data from an opened sound to a specified buffer, using FMOD's internal codecs.
- Sound::seekData Seeks a sound for use with data reading, using FMOD's internal codecs.
- Sound::lock Gives access to a portion or all the sample data of a sound for direct manipulation.
- Sound::unlock Finalizes a previous sample data lock and submits it back to the Sound object.

- FMOD_OPENSTATE These values describe what state a sound is in after FMOD_NONBLOCKING has been used to open it.

Music:

- Sound::getMusicNumChannels Gets the number of music channels inside a MOD/S3M/XM/IT/MIDI file.
- Sound::setMusicChannelVolume Sets the volume of a MOD/S3M/XM/IT/MIDI music channel volume.
- Sound::getMusicChannelVolume Retrieves the volume of a MOD/S3M/XM/IT/MIDI music channel volume.
- Sound::setMusicSpeed Sets the relative speed of MOD/S3M/XM/IT/MIDI music.
- Sound::getMusicSpeed Gets the relative speed of MOD/S3M/XM/IT/MIDI music.

Synchronization / markers:

- Sound::getSyncPoint Retrieve a sync point.
- Sound::getSyncPointInfo Retrieves information on an embedded sync point.
- Sound::getNumSyncPoints Retrieves the number of sync points stored within a sound.
- Sound::addSyncPoint Adds a sync point at a specific time within the sound.
- Sound::deleteSyncPoint Deletes a sync point within the sound.

General:

- Sound::release Frees a sound object.
- Sound::setUserData Sets a user value associated with this object.
- Sound::getUserData Retrieves a user value associated with this object.
- Sound::getSystemObject Retrieves the parent System object.

- FMOD_SOUND_PCMREAD_CALLBACK Read callback used for user created sounds or to intercept FMOD's decoder during a normal sound open.
- FMOD_SOUND_PCMSETPOS_CALLBACK Set position callback for user created sounds or to intercept FMOD's decoder during an API setPositon call.
- FMOD_SOUND_NONBLOCK_CALLBACK Callback to be called when a sound has finished loading, or a non blocking seek is occuring.

## FMOD_OPENSTATE

These values describe what state a sound is in after FMOD_NONBLOCKING has been used to open it.

C
C++
C#
JS

    typedef enum FMOD_OPENSTATE {
      FMOD_OPENSTATE_READY,
      FMOD_OPENSTATE_LOADING,
      FMOD_OPENSTATE_ERROR,
      FMOD_OPENSTATE_CONNECTING,
      FMOD_OPENSTATE_BUFFERING,
      FMOD_OPENSTATE_SEEKING,
      FMOD_OPENSTATE_PLAYING,
      FMOD_OPENSTATE_SETPOSITION,
      FMOD_OPENSTATE_MAX
    } FMOD_OPENSTATE;

    enum OPENSTATE : int
    {
      READY,
      LOADING,
      ERROR,
      CONNECTING,
      BUFFERING,
      SEEKING,
      PLAYING,
      SETPOSITION,
      MAX
    }

    FMOD.OPENSTATE_READY
    FMOD.OPENSTATE_LOADING
    FMOD.OPENSTATE_ERROR
    FMOD.OPENSTATE_CONNECTING
    FMOD.OPENSTATE_BUFFERING
    FMOD.OPENSTATE_SEEKING
    FMOD.OPENSTATE_PLAYING
    FMOD.OPENSTATE_SETPOSITION
    FMOD.OPENSTATE_MAX

FMOD_OPENSTATE_READY
  Opened and ready to play.
FMOD_OPENSTATE_LOADING
  Initial load in progress.
FMOD_OPENSTATE_ERROR
  Failed to open - file not found, out of memory etc. See return value of Sound::getOpenState for what happened.
FMOD_OPENSTATE_CONNECTING
  Connecting to remote host (internet sounds only).
FMOD_OPENSTATE_BUFFERING
  Buffering data.
FMOD_OPENSTATE_SEEKING
  Seeking to subsound and re-flushing stream buffer.
FMOD_OPENSTATE_PLAYING
  Ready and playing, but not possible to release at this time without stalling the main thread.
FMOD_OPENSTATE_SETPOSITION
  Seeking within a stream to a different position.
FMOD_OPENSTATE_MAX
  Maximum number of open state types.

With streams, if you are using FMOD_NONBLOCKING, note that if the user calls Sound::getSubSound, a stream will go into FMOD_OPENSTATE_SEEKING state and sound related commands will return FMOD_ERR_NOTREADY.

With streams, if you are using FMOD_NONBLOCKING, note that if the user calls Channel::getPosition, a stream will go into FMOD_OPENSTATE_SETPOSITION state and sound related commands will return FMOD_ERR_NOTREADY.

See Also: Sound::getOpenState, FMOD_MODE

## Sound::addSyncPoint

Adds a sync point at a specific time within the sound.

C
C++
C#
JS

    FMOD_RESULT Sound::addSyncPoint(
      unsigned int offset,
      FMOD_TIMEUNIT offsettype,
      const char *name,
      FMOD_SYNCPOINT **point
    );

    FMOD_RESULT FMOD_Sound_AddSyncPoint(
      FMOD_SOUND *sound,
      unsigned int offset,
      FMOD_TIMEUNIT offsettype,
      const char *name,
      FMOD_SYNCPOINT **point
    );

    RESULT Sound.addSyncPoint(
      uint offset,
      TIMEUNIT offsettype,
      string name,
      out IntPtr point
    );

    Sound.addSyncPoint(
      offset,
      offsettype,
      name,
      point
    );

offset
  Offset value.
offsettype
  `offset` unit type. (FMOD_TIMEUNIT)
name Opt
  Sync point name. (UTF-8 string)
point Out Opt
  Sync point. (FMOD_SYNCPOINT)

For more information on sync points see Sync Points.

See Also: Sound::getNumSyncPoints, Sound::getSyncPoint, Sound::getSyncPointInfo, Sound::deleteSyncPoint

## Sound::deleteSyncPoint

Deletes a sync point within the sound.

C
C++
C#
JS

    FMOD_RESULT Sound::deleteSyncPoint(
      FMOD_SYNCPOINT *point
    );

    FMOD_RESULT FMOD_Sound_DeleteSyncPoint(
      FMOD_SOUND *sound,
      FMOD_SYNCPOINT *point
    );

    RESULT Sound.deleteSyncPoint(
      IntPtr point
    );

    Sound.deleteSyncPoint(
      point
    );

point
  Sync point. (FMOD_SYNCPOINT)

For for more information on sync points see Sync Points.

See Also: Sound::addSyncPoint, Sound::getNumSyncPoints, Sound::getSyncPoint

## FMOD_SOUND_FORMAT

These definitions describe the native format of the hardware or software buffer that will be used.

C
C++
C#
JS

    typedef enum FMOD_SOUND_FORMAT {
      FMOD_SOUND_FORMAT_NONE,
      FMOD_SOUND_FORMAT_PCM8,
      FMOD_SOUND_FORMAT_PCM16,
      FMOD_SOUND_FORMAT_PCM24,
      FMOD_SOUND_FORMAT_PCM32,
      FMOD_SOUND_FORMAT_PCMFLOAT,
      FMOD_SOUND_FORMAT_BITSTREAM,
      FMOD_SOUND_FORMAT_MAX
    } FMOD_SOUND_FORMAT;

    enum SOUND_FORMAT
    {
      NONE,
      PCM8,
      PCM16,
      PCM24,
      PCM32,
      PCMFLOAT,
      BITSTREAM,
      MAX
    }

    FMOD.SOUND_FORMAT_NONE
    FMOD.SOUND_FORMAT_PCM8
    FMOD.SOUND_FORMAT_PCM16
    FMOD.SOUND_FORMAT_PCM24
    FMOD.SOUND_FORMAT_PCM32
    FMOD.SOUND_FORMAT_PCMFLOAT
    FMOD.SOUND_FORMAT_BITSTREAM
    FMOD.SOUND_FORMAT_MAX

FMOD_SOUND_FORMAT_NONE
  Uninitalized / unknown.
FMOD_SOUND_FORMAT_PCM8
  8bit integer PCM data.
FMOD_SOUND_FORMAT_PCM16
  16bit integer PCM data.
FMOD_SOUND_FORMAT_PCM24
  24bit integer PCM data.
FMOD_SOUND_FORMAT_PCM32
  32bit integer PCM data.
FMOD_SOUND_FORMAT_PCMFLOAT
  32bit floating point PCM data.
FMOD_SOUND_FORMAT_BITSTREAM
  Sound data is in its native compressed format. See FMOD_CREATECOMPRESSEDSAMPLE
FMOD_SOUND_FORMAT_MAX
  Maximum number of sound formats supported.

See Also: System::createSound, Sound::getFormat

## Sound::get3DConeSettings

Retrieves the inside and outside angles of the 3D projection cone and the outside volume.

C
C++
C#
JS

    FMOD_RESULT Sound::get3DConeSettings(
      float *insideconeangle,
      float *outsideconeangle,
      float *outsidevolume
    );

    FMOD_RESULT FMOD_Sound_Get3DConeSettings(
      FMOD_SOUND *sound,
      float *insideconeangle,
      float *outsideconeangle,
      float *outsidevolume
    );

    RESULT Sound.get3DConeSettings(
      out float insideconeangle,
      out float outsideconeangle,
      out float outsidevolume
    );

    Sound.get3DConeSettings(
      insideconeangle,
      outsideconeangle,
      outsidevolume
    );

insideconeangle Out Opt

  Inside cone angle. This is the angle within which the sound is unattenuated.

  - Units: Degrees
  - Range: [0, `outsideconeangle`]
  - Default: 360
outsideconeangle Out Opt

  Outside cone angle. This is the angle outside of which the sound is attenuated to its outside volume.

  - Units: Degrees
  - Range: [`insideconeangle`, 360]
  - Default: 360
outsidevolume Out Opt

  Cone outside volume.

  - Units: Linear
  - Range: [0, 1]
  - Default: 1

See Also: Sound::set3DConeSettings

## Sound::get3DCustomRolloff

Retrieves the current custom rolloff shape for 3D distance attenuation.

C
C++
C#
JS

    FMOD_RESULT Sound::get3DCustomRolloff(
      FMOD_VECTOR **points,
      int *numpoints
    );

    FMOD_RESULT FMOD_Sound_Get3DCustomRolloff(
      FMOD_SOUND *sound,
      FMOD_VECTOR **points,
      int *numpoints
    );

    RESULT Sound.get3DCustomRolloff(
      out IntPtr points,
      out int numpoints
    );

    Sound.get3DCustomRolloff(
      points,
      numpoints
    );

points Out Opt
  Array of points sorted by distance where x = distance and y = volume from 0 to 1. (FMOD_VECTOR)
numpoints Out Opt
  Number of `points`.

See Also: Sound::set3DCustomRolloff

## Sound::get3DMinMaxDistance

Retrieve the minimum and maximum audible distance for a 3D sound.

C
C++
C#
JS

    FMOD_RESULT Sound::get3DMinMaxDistance(
      float *min,
      float *max
    );

    FMOD_RESULT FMOD_Sound_Get3DMinMaxDistance(
      FMOD_SOUND *sound,
      float *min,
      float *max
    );

    RESULT Sound.get3DMinMaxDistance(
      out float min,
      out float max
    );

    Sound.get3DMinMaxDistance(
      min,
      max
    );

min Out Opt

  Minimum volume distance for the sound.

  - Units: Distance units
  - Default: 1
max Out Opt

  Maximum volume distance for the sound.

  - Units: Distance units
  - Default: 10000

See Also: Sound::set3DMinMaxDistance

## Sound::getDefaults

Retrieves a sound's default playback attributes.

C
C++
C#
JS

    FMOD_RESULT Sound::getDefaults(
      float *frequency,
      int *priority
    );

    FMOD_RESULT FMOD_Sound_GetDefaults(
      FMOD_SOUND *sound,
      float *frequency,
      int *priority
    );

    RESULT Sound.getDefaults(
      out float frequency,
      out int priority
    );

    Sound.getDefaults(
      frequency,
      priority
    );

frequency Out Opt

  Default playback frequency.

  - Units: Hertz
  - Default: 48000
priority Out Opt

  Default priority where 0 is the highest priority.

  - Range: [0, 256]
  - Default: 128

See Also: Sound::setDefaults

## Sound::getFormat

Returns format information about the sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getFormat(
      FMOD_SOUND_TYPE *type,
      FMOD_SOUND_FORMAT *format,
      int *channels,
      int *bits
    );

    FMOD_RESULT FMOD_Sound_GetFormat(
      FMOD_SOUND *sound,
      FMOD_SOUND_TYPE *type,
      FMOD_SOUND_FORMAT *format,
      int *channels,
      int *bits
    );

    RESULT Sound.getFormat(
      out SOUND_TYPE type,
      out SOUND_FORMAT format,
      out int channels,
      out int bits
    );

    Sound.getFormat(
      type,
      format,
      channels,
      bits
    );

type Out Opt
  Type of sound. (FMOD_SOUND_TYPE)
format Out Opt
  Format of the sound. (FMOD_SOUND_FORMAT)
channels Out Opt
  Number of channels.
bits Out Opt
  Number of bits per sample, corresponding to `format`.

## Sound::getLength

Retrieves the length using the specified time unit.

C
C++
C#
JS

    FMOD_RESULT Sound::getLength(
      unsigned int *length,
      FMOD_TIMEUNIT lengthtype
    );

    FMOD_RESULT FMOD_Sound_GetLength(
      FMOD_SOUND *sound,
      unsigned int *length,
      FMOD_TIMEUNIT lengthtype
    );

    RESULT Sound.getLength(
      out uint length,
      TIMEUNIT lengthtype
    );

    Sound.getLength(
      length,
      lengthtype
    );

length Out
  Sound length in units specified by `lengthtype`.
lengthtype
  Time unit type to retrieve into `length`. (FMOD_TIMEUNIT)

`lengthtype` must be valid for the file format. For example, an MP3 file does not support FMOD_TIMEUNIT_MODORDER.

A `length` of 0xFFFFFFFF means it is of unlimited length, such as an internet radio stream or MOD/S3M/XM/IT file which may loop forever.

Note: Using a VBR (Variable Bit Rate) source that does not have metadata containing its accurate length (such as un-tagged MP3 or MOD/S3M/XM/IT) may return inaccurate length values.
For these formats, use FMOD_ACCURATETIME when creating the sound. This will cause a slight delay and memory increase, as FMOD will scan the whole during creation to find the correct length. This flag also creates a seek table to enable sample accurate seeking.

See Also: System::createSound

## Sound::getLoopCount

Retrieves the sound's loop count.

C
C++
C#
JS

    FMOD_RESULT Sound::getLoopCount(
      int *loopcount
    );

    FMOD_RESULT FMOD_Sound_GetLoopCount(
      FMOD_SOUND *sound,
      int *loopcount
    );

    RESULT Sound.getLoopCount(
      out int loopcount
    );

    Sound.getLoopCount(
      loopcount
    );

loopcount Out

  Number of times to loop before final playback where -1 is always loop. 0 means no loop.

  - Range: [-1, inf)
  - Default: -1

Unlike the channel loop count function, this function simply returns the value set with Sound::setLoopCount. It does not decrement as it plays (especially seeing as one sound can be played multiple times).

See Also: Sound::setLoopCount, Channel::setLoopCount

## Sound::getLoopPoints

Retrieves the loop points for a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getLoopPoints(
      unsigned int *loopstart,
      FMOD_TIMEUNIT loopstarttype,
      unsigned int *loopend,
      FMOD_TIMEUNIT loopendtype
    );

    FMOD_RESULT FMOD_Sound_GetLoopPoints(
      FMOD_SOUND *sound,
      unsigned int *loopstart,
      FMOD_TIMEUNIT loopstarttype,
      unsigned int *loopend,
      FMOD_TIMEUNIT loopendtype
    );

    RESULT Sound.getLoopPoints(
      out uint loopstart,
      TIMEUNIT loopstarttype,
      out uint loopend,
      TIMEUNIT loopendtype
    );

    Sound.getLoopPoints(
      loopstart,
      loopstarttype,
      loopend,
      loopendtype
    );

loopstart Out Opt
  Loop start point.
loopstarttype
  Time format of `loopstart`. (FMOD_TIMEUNIT)
loopend Out Opt
  Loop end point.
loopendtype
  Time format of `loopend`. (FMOD_TIMEUNIT)

The values from `loopstart` and `loopend` are inclusive, which means these positions will be played.

See Also: Sound::setLoopPoints

## Sound::getMode

Retrieves the mode of a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getMode(
      FMOD_MODE *mode
    );

    FMOD_RESULT FMOD_Sound_GetMode(
      FMOD_SOUND *sound,
      FMOD_MODE *mode
    );

    RESULT Sound.getMode(
      out MODE mode
    );

    Sound.getMode(
      mode
    );

mode Out
  Current mode. (FMOD_MODE)

The mode will be dependent on the mode set by a call to System::createSound, System::createStream or Sound::setMode.

See Also: ChannelControl::setMode, ChannelControl::getMode

## Sound::getMusicChannelVolume

Retrieves the volume of a MOD/S3M/XM/IT/MIDI music channel volume.

C
C++
C#
JS

    FMOD_RESULT Sound::getMusicChannelVolume(
      int channel,
      float *volume
    );

    FMOD_RESULT FMOD_Sound_GetMusicChannelVolume(
      FMOD_SOUND *sound,
      int channel,
      float *volume
    );

    RESULT Sound.getMusicChannelVolume(
      int channel,
      out float volume
    );

    Sound.getMusicChannelVolume(
      channel,
      volume
    );

channel
  MOD/S3M/XM/IT/MIDI music subchannel to retrieve the volume for.
volume Out

  Volume of the channel.

  - Units: Linear
  - Range: [0, 1]
  - Default: 1

See Also: Sound::setMusicChannelVolume

## Sound::getMusicNumChannels

Gets the number of music channels inside a MOD/S3M/XM/IT/MIDI file.

C
C++
C#
JS

    FMOD_RESULT Sound::getMusicNumChannels(
      int *numchannels
    );

    FMOD_RESULT FMOD_Sound_GetMusicNumChannels(
      FMOD_SOUND *sound,
      int *numchannels
    );

    RESULT Sound.getMusicNumChannels(
      out int numchannels
    );

    Sound.getMusicNumChannels(
      numchannels
    );

numchannels Out
  Number of music channels used in the song.

See Also: Sound::setMusicChannelVolume, Sound::getMusicChannelVolume

## Sound::getMusicSpeed

Gets the relative speed of MOD/S3M/XM/IT/MIDI music.

C
C++
C#
JS

    FMOD_RESULT Sound::getMusicSpeed(
      float *speed
    );

    FMOD_RESULT FMOD_Sound_GetMusicSpeed(
      FMOD_SOUND *sound,
      float *speed
    );

    RESULT Sound.getMusicSpeed(
      out float speed
    );

    Sound.getMusicSpeed(
      speed
    );

speed Out
  Speed of the song.

See Also: Sound::setMusicSpeed

## Sound::getName

Retrieves the name of a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getName(
      char *name,
      int namelen
    );

    FMOD_RESULT FMOD_Sound_GetName(
      FMOD_SOUND *sound,
      char *name,
      int namelen
    );

    RESULT Sound.getName(
      out string name,
      int namelen
    );

    Sound.getName(
      name
    );

name Out
  Name of the sound. (UTF-8 string)
namelen

  Length of buffer to receive `name`.

  - Units: Bytes

if FMOD_LOWMEM has been specified in System::createSound, this function will return "(null)".

## Sound::getNumSubSounds

Retrieves the number of subsounds stored within a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getNumSubSounds(
      int *numsubsounds
    );

    FMOD_RESULT FMOD_Sound_GetNumSubSounds(
      FMOD_SOUND *sound,
      int *numsubsounds
    );

    RESULT Sound.getNumSubSounds(
      out int numsubsounds
    );

    Sound.getNumSubSounds(
      numsubsounds
    );

numsubsounds Out
  Number of subsounds.

A format that has subsounds is a container format, such as FSB, DLS, MOD, S3M, XM, IT.

See Also: Sound::getSubSound

## Sound::getNumSyncPoints

Retrieves the number of sync points stored within a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getNumSyncPoints(
      int *numsyncpoints
    );

    FMOD_RESULT FMOD_Sound_GetNumSyncPoints(
      FMOD_SOUND *sound,
      int *numsyncpoints
    );

    RESULT Sound.getNumSyncPoints(
      out int numsyncpoints
    );

    Sound.getNumSyncPoints(
      numsyncpoints
    );

numsyncpoints Out
  Number of sync points.

For for more information on sync points see Sync Points.

See Also: Sound::getSyncPoint, Sound::getSyncPointInfo, Sound::addSyncPoint, Sound::deleteSyncPoint

## Sound::getNumTags

Retrieves the number of metadata tags.

C
C++
C#
JS

    FMOD_RESULT Sound::getNumTags(
      int *numtags,
      int *numtagsupdated
    );

    FMOD_RESULT FMOD_Sound_GetNumTags(
      FMOD_SOUND *sound,
      int *numtags,
      int *numtagsupdated
    );

    RESULT Sound.getNumTags(
      out int numtags,
      out int numtagsupdated
    );

    Sound.getNumTags(
      numtags,
      numtagsupdated
    );

numtags Out Opt
  Number of tags.
numtagsupdated Out Opt
  Number of tags updated since this function was last called.

'Tags' are metadata stored within a sound file. These can be things like a song's name, composer etc.

`numtagsupdated` could be periodically checked to see if new tags are available in certain circumstances. This might be the case with internet based streams (i.e. shoutcast or icecast) where the name of the song or other attributes might change.

See Also: Sound::getTag

## Sound::getOpenState

Retrieves the state a sound is in after being opened with the non blocking flag, or the current state of the streaming buffer.

C
C++
C#
JS

    FMOD_RESULT Sound::getOpenState(
      FMOD_OPENSTATE *openstate,
      unsigned int *percentbuffered,
      bool *starving,
      bool *diskbusy
    );

    FMOD_RESULT FMOD_Sound_GetOpenState(
      FMOD_SOUND *sound,
      FMOD_OPENSTATE *openstate,
      unsigned int *percentbuffered,
      FMOD_BOOL *starving,
      FMOD_BOOL *diskbusy
    );

    RESULT Sound.getOpenState(
      out OPENSTATE openstate,
      out uint percentbuffered,
      out bool starving,
      out bool diskbusy
    );

    Sound.getOpenState(
      openstate,
      percentbuffered,
      starving,
      diskbusy
    );

openstate Out Opt
  Open state of a sound. (FMOD_OPENSTATE)
percentbuffered Out Opt

  Filled percentage of a stream's file buffer.

  - Units: Percent
  - Range: [0, 100]
starving Out Opt

  Starving state. true if a stream has decoded more than the stream file buffer has ready.

  - Units: Boolean
diskbusy Out Opt

  Disk is currently being accessed for this sound.

  - Units: Boolean

When a sound is opened with FMOD_NONBLOCKING, it is opened and prepared in the background, or asynchronously. This allows the main application to execute without stalling on audio loads.
This function will describe the state of the asynchronous load routine i.e. whether it has succeeded, failed or is still in progress.

If 'starving' is true, then you will most likely hear a stuttering/repeating sound as the decode buffer loops on itself and replays old data.
With the ability to detect stream starvation, muting the sound with ChannelControl::setMute will keep the stream quiet until it is not starving any more.

Note: Always check 'openstate' to determine the state of the sound. Do not assume that if this function returns FMOD_OK then the sound has finished loading.

See Also: FMOD_MODE

## Sound::getSoundGroup

Retrieves the sound's current sound group.

C
C++
C#
JS

    FMOD_RESULT Sound::getSoundGroup(
      SoundGroup **soundgroup
    );

    FMOD_RESULT FMOD_Sound_GetSoundGroup(
      FMOD_SOUND *sound,
      FMOD_SOUNDGROUP **soundgroup
    );

    RESULT Sound.getSoundGroup(
      out SoundGroup soundgroup
    );

    Sound.getSoundGroup(
      soundgroup
    );

soundgroup Out
  Sound's current sound group. (SoundGroup)

See Also: Sound::setSoundGroup, System::getMasterSoundGroup

## Sound::getSubSound

Retrieves a handle to a Sound object that is contained within the parent sound.

C
C++
C#
JS

    FMOD_RESULT Sound::getSubSound(
      int index,
      Sound **subsound
    );

    FMOD_RESULT FMOD_Sound_GetSubSound(
      FMOD_SOUND *sound,
      int index,
      FMOD_SOUND **subsound
    );

    RESULT Sound.getSubSound(
      int index,
      out Sound subsound
    );

    Sound.getSubSound(
      index,
      subsound
    );

index

  Index of the subsound.

  - Range: [0, Sound::getNumSubSounds)
subsound Out
  Subsound object. (Sound)

If the sound is a stream and FMOD_NONBLOCKING was not used, then this call will perform a blocking seek/flush to the specified subsound.

If FMOD_NONBLOCKING was used to open this sound and the sound is a stream, FMOD will do a non blocking seek/flush and set the state of the subsound to FMOD_OPENSTATE_SEEKING.

The sound won't be ready to be used when FMOD_NONBLOCKING is used, until the state of the sound becomes FMOD_OPENSTATE_READY or FMOD_OPENSTATE_ERROR.

See Also: Sound::getSubSoundParent, System::createSound

## Sound::getSubSoundParent

Retrieves the parent Sound object that contains this subsound.

C
C++
C#
JS

    FMOD_RESULT Sound::getSubSoundParent(
      Sound **parentsound
    );

    FMOD_RESULT FMOD_Sound_GetSubSoundParent(
      FMOD_SOUND *sound,
      FMOD_SOUND **parentsound
    );

    RESULT Sound.getSubSoundParent(
      out Sound parentsound
    );

    Sound.getSubSoundParent(
      parentsound
    );

parentsound Out
  Parent sound object. (Sound)

If the sound is not a subsound, the `parentsound` will be null.

See Also: Sound::getNumSubSounds, Sound::getSubSound

## Sound::getSyncPoint

Retrieve a sync point.

C
C++
C#
JS

    FMOD_RESULT Sound::getSyncPoint(
      int index,
      FMOD_SYNCPOINT **point
    );

    FMOD_RESULT FMOD_Sound_GetSyncPoint(
      FMOD_SOUND *sound,
      int index,
      FMOD_SYNCPOINT **point
    );

    RESULT Sound.getSyncPoint(
      int index,
      out IntPtr point
    );

    Sound.getSyncPoint(
      index,
      point
    );

index

  Index of the sync point.

  - Range: [0, Sound::getNumSyncPoints)
point Out
  Sync point. (FMOD_SYNCPOINT)

For for more information on sync points see Sync Points.

See Also: Sound::getNumSyncPoints, Sound::getSyncPointInfo, Sound::addSyncPoint, Sound::deleteSyncPoint

## Sound::getSyncPointInfo

Retrieves information on an embedded sync point.

C
C++
C#
JS

    FMOD_RESULT Sound::getSyncPointInfo(
      FMOD_SYNCPOINT *point,
      char *name,
      int namelen,
      unsigned int *offset,
      FMOD_TIMEUNIT offsettype
    );

    FMOD_RESULT FMOD_Sound_GetSyncPointInfo(
      FMOD_SOUND *sound,
      FMOD_SYNCPOINT *point,
      char *name,
      int namelen,
      unsigned int *offset,
      FMOD_TIMEUNIT offsettype
    );

    RESULT Sound.getSyncPointInfo(
      IntPtr point,
      out string name,
      int namelen,
      out uint offset,
      TIMEUNIT offsettype
    );

    Sound.getSyncPointInfo(
      point,
      name,
      namelen,
      offset,
      offsettype
    );

point
  Sync point. (FMOD_SYNCPOINT)
name Out Opt
  Name of the syncpoint. (UTF-8 string)
namelen

  Size of `name`.

  - Units: Bytes
offset Out Opt
  Offset of the syncpoint.
offsettype
  Format of `offset`. (FMOD_TIMEUNIT)

For for more information on sync points see Sync Points.

See Also: Sound::getNumSyncPoints, Sound::getSyncPoint, Sound::addSyncPoint, Sound::deleteSyncPoint

## Sound::getSystemObject

Retrieves the parent System object.

C
C++
C#
JS

    FMOD_RESULT Sound::getSystemObject(
      System **system
    );

    FMOD_RESULT FMOD_Sound_GetSystemObject(
      FMOD_SOUND *sound,
      FMOD_SYSTEM **system
    );

    RESULT Sound.getSystemObject(
      out System system
    );

    Sound.getSystemObject(
      system
    );

system Out
  System object. (System)

See Also: System::createSound

## Sound::getTag

Retrieves a metadata tag.

C
C++
C#
JS

    FMOD_RESULT Sound::getTag(
      const char *name,
      int index,
      FMOD_TAG *tag
    );

    FMOD_RESULT FMOD_Sound_GetTag(
      FMOD_SOUND *sound,
      const char *name,
      int index,
      FMOD_TAG *tag
    );

    RESULT Sound.getTag(
      string name,
      int index,
      out TAG tag
    );

    Sound.getTag(
      name,
      index,
      tag
    );

name
  Name of a type of tag to retrieve. (UTF-8 string). Specify null to retrieve all types of tags.
index Opt

  Index into the tag list as restricted by `name`.

  - Range: [0, Sound::getNumTags)
tag Out
  Tag info structure. (FMOD_TAG)

'Tags' are metadata stored within a sound file. These can be things like a song's name, composer etc.

The number of tags available can be found with Sound::getNumTags.

The way to display or retrieve tags can be done in 3 different ways:

- All tags can be continuously retrieved by looping from 0 to the numtags value in Sound::getNumTags - 1. Updated tags will refresh automatically, and the 'updated' member of the FMOD_TAG structure will be set to true if a tag has been updated, due to something like a netstream changing the song name for example.
- Tags can be retrieved by specifying -1 as the index and only updating tags that are returned. If all tags are retrieved and this function is called the function will return an error of FMOD_ERR_TAGNOTFOUND.
- Specific tags can be retrieved by specifying a name parameter. The index can be 0 based or -1 in the same fashion as described previously.

Note with netstreams an important consideration must be made between songs, a tag may occur that changes the playback rate of the song. It is up to the user to catch this and reset the playback rate with Channel::setFrequency.
A sample rate change will be signalled with a tag of type FMOD_TAGTYPE_FMOD.

      FMOD_TAG tag;
      while (FMOD_Sound_GetTag(sound, 0, -1, &tag) == FMOD_OK)
      {
        if (tag.type == FMOD_TAGTYPE_FMOD)
        {
            /* When a song changes, the sample rate may also change, so compensate here. */
            if (!strcmp(tag.name, "Sample Rate Change") && channel)
            {
                float frequency = *((float *)tag.data);

                result = FMOD_Channel_SetFrequency(channel, frequency);
                ERRCHECK(result);
            }
        }
      }

      FMOD_TAG tag;
      while (sound->getTag(0, -1, &tag) == FMOD_OK)
      {
        if (tag.type == FMOD_TAGTYPE_FMOD)
        {
            /* When a song changes, the sample rate may also change, so compensate here. */
            if (!strcmp(tag.name, "Sample Rate Change") && channel)
            {
                float frequency = *((float *)tag.data);

                result = channel->setFrequency(frequency);
                ERRCHECK(result);
            }
        }
      }

## Sound::getUserData

Retrieves a user value associated with this object.

C
C++
C#
JS

    FMOD_RESULT Sound::getUserData(
      void **userdata
    );

    FMOD_RESULT FMOD_Sound_GetUserData(
      FMOD_SOUND *sound,
      void **userdata
    );

    RESULT Sound.getUserData(
      out IntPtr userdata
    );

    Sound.getUserData(
      userdata
    );

userdata Out
  Value stored on this object.

See Also: Sound::setUserData

## Sound::lock

Gives access to a portion or all the sample data of a sound for direct manipulation.

C
C++
C#
JS

    FMOD_RESULT Sound::lock(
      unsigned int offset,
      unsigned int length,
      void **ptr1,
      void **ptr2,
      unsigned int *len1,
      unsigned int *len2
    );

    FMOD_RESULT FMOD_Sound_Lock(
      FMOD_SOUND *sound,
      unsigned int offset,
      unsigned int length,
      void **ptr1,
      void **ptr2,
      unsigned int *len1,
      unsigned int *len2
    );

    RESULT Sound.lock(
      uint offset,
      uint length,
      out IntPtr ptr1,
      out IntPtr ptr2,
      out uint len1,
      out uint len2
    );

    Sound.lock(
      offset,
      length,
      ptr1,
      ptr2,
      len1,
      len2
    );

offset

  Offset into the sound's buffer to be retrieved.

  - Units: Bytes
length

  Length of the data required to be retrieved. If `offset` + `length` exceeds the length of the sample buffer, `ptr2` and `len2` will be valid.

  - Units: Bytes
ptr1 Out

  First part of the locked data.

  - Units: Sample Data
ptr2 Out

  Second part of the locked data if the `offset` + `length` has exceeded the length of the sample buffer.

  - Units: Sample Data
len1 Out

  Length of `ptr1`.

  - Units: Bytes
len2 Out

  Length of `ptr2`

  - Units: Bytes

You must always unlock the data again after you have finished with it, using Sound::unlock.

With this function you get access to the raw audio data. If the data is 8, 16, 24 or 32bit PCM data, mono or stereo data, you must take this into consideration when processing the data. See Sample Data for more information.

If the sound is created with FMOD_CREATECOMPRESSEDSAMPLE the data retrieved will be the compressed bitstream.

It is not possible to lock the following:

- A parent sound containing subsounds. A parent sound has no audio data and FMOD_ERR_SUBSOUNDS will be returned.
- A stream / sound created with FMOD_CREATESTREAM. FMOD_ERR_BADCOMMAND will be returned in this case.

The names 'lock'/'unlock' are a legacy reference to older Operating System APIs that used to cause a mutex lock on the data, so that it could not be written to while the 'lock' was in place. This is no longer the case with FMOD and data can be 'locked' multiple times from different places/threads at once.

See Also: System::createSound

## FMOD_SOUND_NONBLOCK_CALLBACK

Callback to be called when a sound has finished loading, or a non blocking seek is occuring.

C
C++
C#
JS

    FMOD_RESULT F_CALLBACK FMOD_SOUND_NONBLOCK_CALLBACK(
      FMOD_SOUND *sound,
      FMOD_RESULT result
    );

    delegate RESULT SOUND_NONBLOCKCALLBACK(
      IntPtr sound,
      RESULT result
    );

Not supported for JavaScript.

sound
  Sound. (Sound)
result
  Error code. (FMOD_RESULT)

Invoked by:

- System::createSound with FMOD_NONBLOCKING flag.
- System::createStream with FMOD_NONBLOCKING flag.
- Channel::setPosition if System::createSound or System::createStream was opened with the FMOD_NONBLOCKING flag.

Return code currently ignored.

Note that for non blocking streams a seek could occur when restarting the sound after the first playthrough. This will result in a callback being triggered again.

Since this callback can occur from the async thread, there are restrictions about what functions can be called during the callback. All Sound functions are safe to call, except for Sound::setSoundGroup and Sound::release. It is also safe to call System::getUserData. The rest of the Core API and the Studio API is not allowed. Calling a non-allowed function will return FMOD_ERR_INVALID_THREAD.

`sound` can be cast to `Sound *`.

See Also: FMOD_CREATESOUNDEXINFO

## FMOD_SOUND_PCMREAD_CALLBACK

Read callback used for user created sounds or to intercept FMOD's decoder during a normal sound open.

C
C++
C#
JS

    FMOD_RESULT F_CALLBACK FMOD_SOUND_PCMREAD_CALLBACK(
      FMOD_SOUND *sound,
      void *data,
      unsigned int datalen
    );

    delegate RESULT SOUND_PCMREADCALLBACK(
      IntPtr sound,
      IntPtr data,
      uint datalen
    );

    function FMOD_SOUND_PCMREAD_CALLBACK(
      sound,
      data,
      datalen
    )

sound
  Sound. (Sound)
data
  PCM data that the user can either read or write to.

- Units: Sample Data

datalen

  Length of the data.

  - Units: Bytes

Invoked by:

- System::createSound
- System::createStream
- Sound::readData

Use cases:

- A FMOD_OPENUSER sound. The callback is used to write PCM data to a user created sound when requested.
- During a normal System::createsound or System::createStream, the read callback will be issued with decoded pcm data, allowing it to be manipulated or copied somewhere else. The return value is ignored.

The format of the sound can be retrieved with Sound::getFormat from this callback. This will allow the user to determine what type of pointer to use if they are not sure what format the sound is.

`sound` can be cast to `Sound *`.

See Also: FMOD_SOUND_PCMSETPOS_CALLBACK, FMOD_CREATESOUNDEXINFO

## FMOD_SOUND_PCMSETPOS_CALLBACK

Set position callback for user created sounds or to intercept FMOD's decoder during an API setPositon call.

C
C++
C#
JS

    FMOD_RESULT F_CALLBACK FMOD_SOUND_PCMSETPOS_CALLBACK(
      FMOD_SOUND *sound,
      int subsound,
      unsigned int position,
      FMOD_TIMEUNIT postype
    );

    delegate RESULT SOUND_PCMSETPOSCALLBACK(
      IntPtr sound,
      int subsound,
      uint position,
      TIMEUNIT postype
    );

    function FMOD_SOUND_PCMSETPOS_CALLBACK(
      sound,
      subsound,
      position,
      postype
    )

sound
  Sound. (Sound)
subsound
  In a multi subsound type sound (ie .FSB or .DLS), this will contain the index into the list of sounds.
position
  Requested seek position.
postype

  `position` type, or FMOD_ERR_FORMAT if the sound is a user created sound and the seek type is unsupported. (FMOD_TIMEUNIT)

  - Default: FMOD_TIMEUNIT_PCM

Invoked by:

- System::createSound
- System::createStream
- Channel::setPosition
- Sound::seekData

Use cases:

- A FMOD_OPENUSER created sound. The callback is used to allow seeking within the user's resource.
- During a normal System::createsound or System::createStream, the setposition callback is purely informational and the return value is ignored.

`sound` can be cast to `Sound *`.

See Also: FMOD_SOUND_PCMREAD_CALLBACK, FMOD_CREATESOUNDEXINFO

## Sound::readData

Reads data from an opened sound to a specified buffer, using FMOD's internal codecs.

C
C++
C#
JS

    FMOD_RESULT Sound::readData(
      void *buffer,
      unsigned int length,
      unsigned int *read
    );

    FMOD_RESULT FMOD_Sound_ReadData(
      FMOD_SOUND *sound,
      void *buffer,
      unsigned int length,
      unsigned int *read
    );

    RESULT Sound.readData(
      IntPtr buffer,
      uint length,
      out uint read
    );

    Sound.readData(
      buffer,
      length,
      read
    );

buffer

  Buffer to read decoded data into.

  - Units: Sample Data
length

  Amount of data to read into `buffer`.

  - Units: Bytes
read Out

  Actual amount of data read. May differ to `length`.

  - Units: Bytes

This can be used for decoding data offline in small pieces (or big pieces), rather than playing and capturing it, or loading the whole file at once and having to Sound::lock / Sound::unlock the data.

If too much data is read, it is possible FMOD_ERR_FILE_EOF will be returned, meaning it is out of data. The 'read' parameter will reflect this by returning a smaller number of bytes read than was requested.

As a non streaming sound reads and decodes the whole file then closes it upon calling System::createSound, Sound::readData will then not work because the file handle is closed. Use FMOD_OPENONLY to stop FMOD reading/decoding the file.
If FMOD_OPENONLY flag is used when opening a sound, it will leave the file handle open, and FMOD will not read/decode any data internally, so the read cursor will stay at position 0. This will allow the user to read the data from the start.

For streams, the streaming engine will decode a small chunk of data and this will advance the read cursor. You need to either use FMOD_OPENONLY to stop the stream pre-buffering or call Sound::seekData to reset the read cursor back to the start of the file, otherwise it will appear as if the start of the stream is missing.
Channel::setPosition will have the same result. These functions will flush the stream buffer and read in a chunk of audio internally. This is why if you want to read from an absolute position you should use Sound::seekData and not the previously mentioned functions.

If you are calling Sound::readData and Sound::seekData on a stream, information functions such as Channel::getPosition may give misleading results. Calling Channel::setPosition will cause the streaming engine to reset and flush the stream, leading to the time values returning to their correct position.

NOTE! Thread safety. If you call this from another stream callback, or any other thread besides the main thread, make sure to mutex the callback with Sound::release in case the sound is still being read from while releasing.

This function is thread safe to call from a stream callback or different thread as long as it doesnt conflict with a call to Sound::release.

See Also: Sound::lock, Sound::unlock

## Sound::release

Frees a sound object.

C
C++
C#
JS

    FMOD_RESULT Sound::release();

    FMOD_RESULT FMOD_Sound_Release(FMOD_SOUND *sound);

    RESULT Sound.release();

    Sound.release();

This will stop any instances of this sound, and free the sound object and its children if it is a multi-sound object.

If the sound was opened with FMOD_NONBLOCKING and hasn't finished opening yet, it will block. Using Sound::getOpenState and checking the open state for FMOD_OPENSTATE_READY and FMOD_OPENSTATE_ERROR is a good way to avoid stalls.

See Also: System::createSound, Sound::getSubSound

## Sound::seekData

Seeks a sound for use with data reading, using FMOD's internal codecs.

C
C++
C#
JS

    FMOD_RESULT Sound::seekData(
      unsigned int pcm
    );

    FMOD_RESULT FMOD_Sound_SeekData(
      FMOD_SOUND *sound,
      unsigned int pcm
    );

    RESULT Sound.seekData(
      uint pcm
    );

    Sound.seekData(
      pcm
    );

pcm

  Seek Offset.

  - Units: Samples

For use in conjunction with Sound::readData and FMOD_OPENONLY.

For streaming sounds, if this function is called, it will advance the internal file pointer but not update the streaming engine. This can lead to de-synchronization of position information for the stream and audible playback.

A stream can reset its stream buffer and position synchronization by calling Channel::setPosition. This causes reset and flush of the stream buffer.

## Sound::set3DConeSettings

Sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.

C
C++
C#
JS

    FMOD_RESULT Sound::set3DConeSettings(
      float insideconeangle,
      float outsideconeangle,
      float outsidevolume
    );

    FMOD_RESULT FMOD_Sound_Set3DConeSettings(
      FMOD_SOUND *sound,
      float insideconeangle,
      float outsideconeangle,
      float outsidevolume
    );

    RESULT Sound.set3DConeSettings(
      float insideconeangle,
      float outsideconeangle,
      float outsidevolume
    );

    Sound.set3DConeSettings(
      insideconeangle,
      outsideconeangle,
      outsidevolume
    );

insideconeangle

  Inside cone angle. This is the angle spread within which the sound is unattenuated.

  - Units: Degrees
  - Range: [0, `outsideconeangle`]
  - Default: 360
outsideconeangle

  Outside cone angle. This is the angle spread outside of which the sound is attenuated to its `outsidevolume`.

  - Units: Degrees
  - Range: [`insideconeangle`, 360]
  - Default: 360
outsidevolume

  Cone outside volume.

  - Units: Linear
  - Range: [0, 1]
  - Default: 1

When ChannelControl::set3DConeOrientation is used and a 3D 'cone' is set up, attenuation will automatically occur for a sound based on the relative angle of the direction the cone is facing, vs the angle between the sound and the listener.

- If the relative angle is within the `insideconeangle`, the sound will not have any attenuation applied.
- If the relative angle is between the `insideconeangle` and `outsideconeangle`, linear volume attenuation (between 1 and `outsidevolume`) is applied between the two angles until it reaches the `outsideconeangle`.
- If the relative angle is outside of the `outsideconeangle` the volume does not attenuate any further.

See Also: Sound::get3DConeSettings, ChannelControl::set3DConeSettings

## Sound::set3DCustomRolloff

Sets a custom rolloff shape for 3D distance attenuation.

C
C++
C#
JS

    FMOD_RESULT Sound::set3DCustomRolloff(
      FMOD_VECTOR *points,
      int numpoints
    );

    FMOD_RESULT FMOD_Sound_Set3DCustomRolloff(
      FMOD_SOUND *sound,
      FMOD_VECTOR *points,
      int numpoints
    );

    RESULT Sound.set3DCustomRolloff(
      ref VECTOR points,
      int numpoints
    );

    Sound.set3DCustomRolloff(
      points,
      numpoints
    );

points
  Array of points sorted by distance, where `x` = distance and `y` = volume from 0 to 1. `z` should be set to 0. Pass null or equivalent to disable custom rolloff. (FMOD_VECTOR)
numpoints
  Number of `points`.

Must be used in conjunction with FMOD_3D_CUSTOMROLLOFF flag to be activated.

This function does not duplicate the memory for the points internally. The memory you pass to FMOD must remain valid while in use.

If FMOD_3D_CUSTOMROLLOFF is set and the rolloff shape is not set, FMOD will revert to FMOD_3D_INVERSEROLLOFF rolloff method.

When a custom rolloff is specified a sound's 3D 'minimum' and 'maximum' distances are ignored.

The distance in-between point values is linearly interpolated until the final point where the last value is held.

If the points are not sorted by distance, an error will result.

    // Defining a custom array of points
    FMOD_VECTOR curve[3] =
    {
        { 0.0f,  1.0f, 0.0f },
        { 2.0f,  0.2f, 0.0f },
        { 20.0f, 0.0f, 0.0f }
    };

See Also: Sound::get3DCustomRolloff, ChannelControl::set3DCustomRolloff

## Sound::set3DMinMaxDistance

Sets the minimum and maximum audible distance for a 3D sound.

C
C++
C#
JS

    FMOD_RESULT Sound::set3DMinMaxDistance(
      float min,
      float max
    );

    FMOD_RESULT FMOD_Sound_Set3DMinMaxDistance(
      FMOD_SOUND *sound,
      float min,
      float max
    );

    RESULT Sound.set3DMinMaxDistance(
      float min,
      float max
    );

    Sound.set3DMinMaxDistance(
      min,
      max
    );

min

  The sound's minimum volume distance, or the distance that the sound has no attenuation due to 3d positioning.

  - Units: Distance units
  - Default: 1
max

  The sound's maximum volume distance, or the distance that no additional attenuation will occur. See below for notes on different maxdistance behaviors.

  - Units: Distance units
  - Default: 10000

The distances are meant to simulate the 'size' of a sound. Reducing the `min` distance will mean the sound appears smaller in the world, and in some modes makes the volume attenuate faster as the listener moves away from the sound.
Increasing the `min` distance simulates a larger sound in the world, and in some modes makes the volume attenuate slower as the listener moves away from the sound.

`max` will affect attenuation differently based on rolloff mode set in the `mode` parameter of System::createSound, System::createStream, Sound::setMode or ChannelControl::setMode.

For these modes the volume will attenuate to 0 volume (silence), when the distance from the sound is equal to or further than the `max` distance:

- FMOD_3D_LINEARROLLOFF
- FMOD_3D_LINEARSQUAREROLLOFF

For these modes the volume will stop attenuating at the point of the `max` distance, without affecting the rate of attenuation:

- FMOD_3D_INVERSEROLLOFF
- FMOD_3D_INVERSETAPEREDROLLOFF

For this mode the `max` distance is ignored:

- FMOD_3D_CUSTOMROLLOFF

See Also: Sound::get3DMinMaxDistance, ChannelControl::set3DMinMaxDistance, ChannelControl::get3DMinMaxDistance, System::set3DSettings

## Sound::setDefaults

Sets a sound's default playback attributes.

When the Sound is played it will use these values without having to specify them later on a per Channel basis.

C
C++
C#
JS

    FMOD_RESULT Sound::setDefaults(
      float frequency,
      int priority
    );

    FMOD_RESULT FMOD_Sound_SetDefaults(
      FMOD_SOUND *sound,
      float frequency,
      int priority
    );

    RESULT Sound.setDefaults(
      float frequency,
      int priority
    );

    Sound.setDefaults(
      frequency,
      priority
    );

frequency

  Default playback frequency.

  - Units: Hertz
  - Default: 48000
priority

  Default priority where 0 is the highest priority.

  - Range: [0, 256]
  - Default: 128

See Also: Sound::getDefaults, System::playSound, System::createSound

## Sound::setLoopCount

Sets the sound to loop a specified number of times before stopping if the playback mode is set to looping.

C
C++
C#
JS

    FMOD_RESULT Sound::setLoopCount(
      int loopcount
    );

    FMOD_RESULT FMOD_Sound_SetLoopCount(
      FMOD_SOUND *sound,
      int loopcount
    );

    RESULT Sound.setLoopCount(
      int loopcount
    );

    Sound.setLoopCount(
      loopcount
    );

loopcount

  Number of times to loop before final playback where -1 is always loop. 0 means no loop.

  - Range: [-1, inf)
  - Default: -1

Changing loop count on an already buffered stream may not produced desired output. See Streaming Issues.

See Also: Sound::setLoopPoints, Sound::getLoopCount

## Sound::setLoopPoints

Sets the loop points within a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::setLoopPoints(
      unsigned int loopstart,
      FMOD_TIMEUNIT loopstarttype,
      unsigned int loopend,
      FMOD_TIMEUNIT loopendtype
    );

    FMOD_RESULT FMOD_Sound_SetLoopPoints(
      FMOD_SOUND *sound,
      unsigned int loopstart,
      FMOD_TIMEUNIT loopstarttype,
      unsigned int loopend,
      FMOD_TIMEUNIT loopendtype
    );

    RESULT Sound.setLoopPoints(
      uint loopstart,
      TIMEUNIT loopstarttype,
      uint loopend,
      TIMEUNIT loopendtype
    );

    Sound.setLoopPoints(
      loopstart,
      loopstarttype,
      loopend,
      loopendtype
    );

loopstart

  Loop start point.

  - Range: [0, loopend)
loopstarttype
  Time format of `loopstart`. (FMOD_TIMEUNIT)
loopend

  Loop end point.

  - Range: [loopstart, Sound::getLength)
loopendtype
  Time format of `loopend`. (FMOD_TIMEUNIT)

The values used for `loopstart` and `loopend` are inclusive, which means these positions will be played.

If a `loopend` is smaller or equal to `loopstart` an error will be returned. The same will happen for any values that are equal or greater than the length of the sound.

Changing loop points on an already buffered stream may not produced desired output. See Streaming Issues.

See Also: Sound::getLoopPoints, Sound::setLoopCount

## Sound::setMode

Sets or alters the mode of a sound.

C
C++
C#
JS

    FMOD_RESULT Sound::setMode(
      FMOD_MODE mode
    );

    FMOD_RESULT FMOD_Sound_SetMode(
      FMOD_SOUND *sound,
      FMOD_MODE mode
    );

    RESULT Sound.setMode(
      MODE mode
    );

    Sound.setMode(
      mode
    );

mode

  Mode bits to set. (FMOD_MODE)

  - Default: FMOD_DEFAULT

When calling this function, note that it will only take effect when the sound is played again with System::playSound.
This is the default for when the sound next plays, not a mode that will suddenly change all currently playing instances of this sound.

Flags supported:

- FMOD_LOOP_OFF
- FMOD_LOOP_NORMAL
- FMOD_LOOP_BIDI
- FMOD_3D_HEADRELATIVE
- FMOD_3D_WORLDRELATIVE
- FMOD_2D
- FMOD_3D
- FMOD_3D_INVERSEROLLOFF
- FMOD_3D_LINEARROLLOFF
- FMOD_3D_LINEARSQUAREROLLOFF
- FMOD_3D_INVERSETAPEREDROLLOFF
- FMOD_3D_CUSTOMROLLOFF
- FMOD_3D_IGNOREGEOMETRY

If FMOD_3D_IGNOREGEOMETRY is not specified, the flag will be cleared if it was specified previously.

Changing mode on an already buffered stream may not produced desired output. See Streaming Issues.

See Also: Streaming Issues, Sound::getMode, Sound::setLoopPoints, System::playSound

## Sound::setMusicChannelVolume

Sets the volume of a MOD/S3M/XM/IT/MIDI music channel volume.

C
C++
C#
JS

    FMOD_RESULT Sound::setMusicChannelVolume(
      int channel,
      float volume
    );

    FMOD_RESULT FMOD_Sound_SetMusicChannelVolume(
      FMOD_SOUND *sound,
      int channel,
      float volume
    );

    RESULT Sound.setMusicChannelVolume(
      int channel,
      float volume
    );

    Sound.setMusicChannelVolume(
      channel,
      volume
    );

channel
  MOD/S3M/XM/IT/MIDI music subchannel to set a linear volume for.
volume

  Volume of the channel.

  - Units: Linear
  - Range: [0, 1]
  - Default: 1

See Also: Sound::getMusicNumChannels, Sound::getMusicChannelVolume

## Sound::setMusicSpeed

Sets the relative speed of MOD/S3M/XM/IT/MIDI music.

C
C++
C#
JS

    FMOD_RESULT Sound::setMusicSpeed(
      float speed
    );

    FMOD_RESULT FMOD_Sound_SetMusicSpeed(
      FMOD_SOUND *sound,
      float speed
    );

    RESULT Sound.setMusicSpeed(
      float speed
    );

    Sound.setMusicSpeed(
      speed
    );

speed

  Speed of the song.

  - Units: Linear
  - Range: [0.01, 100]
  - Default: 1

See Also: Sound::getMusicSpeed

## Sound::setSoundGroup

Moves the sound from its existing SoundGroup to the specified sound group.

C
C++
C#
JS

    FMOD_RESULT Sound::setSoundGroup(
      SoundGroup *soundgroup
    );

    FMOD_RESULT FMOD_Sound_SetSoundGroup(
      FMOD_SOUND *sound,
      FMOD_SOUNDGROUP *soundgroup
    );

    RESULT Sound.setSoundGroup(
      SoundGroup soundgroup
    );

    Sound.setSoundGroup(
      soundgroup
    );

soundgroup
  Sound group to move the sound to. (SoundGroup)

By default, a sound is located in the 'master sound group'. This can be retrieved with System::getMasterSoundGroup.

See Also: Sound::getSoundGroup, System::createSoundGroup, SoundGroup::setMaxAudible

## Sound::setUserData

Sets a user value associated with this object.

C
C++
C#
JS

    FMOD_RESULT Sound::setUserData(
      void *userdata
    );

    FMOD_RESULT FMOD_Sound_SetUserData(
      FMOD_SOUND *sound,
      void *userdata
    );

    RESULT Sound.setUserData(
      IntPtr userdata
    );

    Sound.setUserData(
      userdata
    );

userdata
  Value stored on this object.

Associates some data with this object to give it context.

See Also: Sound::getUserData

## FMOD_SOUND_TYPE

Recognized audio formats that can be loaded into a Sound.

C
C++
C#
JS

    typedef enum FMOD_SOUND_TYPE {
      FMOD_SOUND_TYPE_UNKNOWN,
      FMOD_SOUND_TYPE_AIFF,
      FMOD_SOUND_TYPE_ASF,
      FMOD_SOUND_TYPE_DLS,
      FMOD_SOUND_TYPE_FLAC,
      FMOD_SOUND_TYPE_FSB,
      FMOD_SOUND_TYPE_IT,
      FMOD_SOUND_TYPE_MIDI,
      FMOD_SOUND_TYPE_MOD,
      FMOD_SOUND_TYPE_MPEG,
      FMOD_SOUND_TYPE_OGGVORBIS,
      FMOD_SOUND_TYPE_PLAYLIST,
      FMOD_SOUND_TYPE_RAW,
      FMOD_SOUND_TYPE_S3M,
      FMOD_SOUND_TYPE_USER,
      FMOD_SOUND_TYPE_WAV,
      FMOD_SOUND_TYPE_XM,
      FMOD_SOUND_TYPE_XMA,
      FMOD_SOUND_TYPE_AUDIOQUEUE,
      FMOD_SOUND_TYPE_AT9,
      FMOD_SOUND_TYPE_VORBIS,
      FMOD_SOUND_TYPE_MEDIA_FOUNDATION,
      FMOD_SOUND_TYPE_MEDIACODEC,
      FMOD_SOUND_TYPE_FADPCM,
      FMOD_SOUND_TYPE_OPUS,
      FMOD_SOUND_TYPE_MAX
    } FMOD_SOUND_TYPE;

    enum SOUND_TYPE
    {
      UNKNOWN,
      AIFF,
      ASF,
      DLS,
      FLAC,
      FSB,
      IT,
      MIDI,
      MOD,
      MPEG,
      OGGVORBIS,
      PLAYLIST,
      RAW,
      S3M,
      USER,
      WAV,
      XM,
      XMA,
      AUDIOQUEUE,
      AT9,
      VORBIS,
      MEDIA_FOUNDATION,
      MEDIACODEC,
      FADPCM,
      OPUS,
      MAX,
    }

    FMOD.SOUND_TYPE_UNKNOWN
    FMOD.SOUND_TYPE_AIFF
    FMOD.SOUND_TYPE_ASF
    FMOD.SOUND_TYPE_DLS
    FMOD.SOUND_TYPE_FLAC
    FMOD.SOUND_TYPE_FSB
    FMOD.SOUND_TYPE_IT
    FMOD.SOUND_TYPE_MIDI
    FMOD.SOUND_TYPE_MOD
    FMOD.SOUND_TYPE_MPEG
    FMOD.SOUND_TYPE_OGGVORBIS
    FMOD.SOUND_TYPE_PLAYLIST
    FMOD.SOUND_TYPE_RAW
    FMOD.SOUND_TYPE_S3M
    FMOD.SOUND_TYPE_USER
    FMOD.SOUND_TYPE_WAV
    FMOD.SOUND_TYPE_XM
    FMOD.SOUND_TYPE_XMA
    FMOD.SOUND_TYPE_AUDIOQUEUE
    FMOD.SOUND_TYPE_AT9
    FMOD.SOUND_TYPE_VORBIS
    FMOD.SOUND_TYPE_MEDIA_FOUNDATION
    FMOD.SOUND_TYPE_MEDIACODEC
    FMOD.SOUND_TYPE_FADPCM
    FMOD.SOUND_TYPE_OPUS
    FMOD.SOUND_TYPE_MAX

FMOD_SOUND_TYPE_UNKNOWN
  Unknown or custom codec plugin.
FMOD_SOUND_TYPE_AIFF
  Audio Interchange File Format (.aif, .aiff). Uncompressed integer formats only.
FMOD_SOUND_TYPE_ASF
  Microsoft Advanced Systems Format (.asf, .wma, .wmv). Platform provided decoder, available only on Windows.
FMOD_SOUND_TYPE_DLS
  Downloadable Sound (.dls). Multi-sound bank format used by MIDI (.mid).
FMOD_SOUND_TYPE_FLAC
  Free Lossless Audio Codec (.flac).
FMOD_SOUND_TYPE_FSB
  FMOD Sample Bank (.fsb). Proprietary multi-sound bank format. Supported encodings: PCM16, FADPCM, Vorbis, AT9, XMA, Opus.
FMOD_SOUND_TYPE_IT
  Impulse Tracker (.it).
FMOD_SOUND_TYPE_MIDI
  Musical Instrument Digital Interface (.mid).
FMOD_SOUND_TYPE_MOD
  Protracker / Fasttracker Module File (.mod).
FMOD_SOUND_TYPE_MPEG
  Moving Picture Experts Group (.mp2, .mp3). Also supports .wav (RIFF) container format.
FMOD_SOUND_TYPE_OGGVORBIS
  Ogg Vorbis (.ogg).
FMOD_SOUND_TYPE_PLAYLIST
  Play list information container (.asx, .pls, .m3u, .wax). No audio, tags only.
FMOD_SOUND_TYPE_RAW
  Raw uncompressed PCM data (.raw).
FMOD_SOUND_TYPE_S3M
  ScreamTracker 3 Module (.s3m).
FMOD_SOUND_TYPE_USER
  User created sound.
FMOD_SOUND_TYPE_WAV
  Microsoft Waveform Audio File Format (.wav). Supported encodings: Uncompressed PCM, IMA ADPCM. Platform provided ACM decoder extensions, available only on Windows.
FMOD_SOUND_TYPE_XM
  FastTracker 2 Extended Module (.xm).
FMOD_SOUND_TYPE_XMA
  Microsoft XMA bit-stream supported by FSB (.fsb) container format. Platform provided decoder, available only on Xbox.
FMOD_SOUND_TYPE_AUDIOQUEUE
  Apple Audio Queue decoder (.mp4, .m4a, .mp3). Supported encodings: AAC, ALAC, MP3. Platform provided decoder, available only on iOS / tvOS devices.
FMOD_SOUND_TYPE_AT9
  Sony ATRAC9 bit-stream supported by FSB (.fsb) container format. Platform provided decoder, available only on PlayStation.
FMOD_SOUND_TYPE_VORBIS
  Vorbis bit-stream supported by FSB (.fsb) container format.
FMOD_SOUND_TYPE_MEDIA_FOUNDATION
  Microsoft Media Foundation decoder (.asf, .wma, .wmv, .mp4, .m4a). Platform provided decoder, available only on UWP.
FMOD_SOUND_TYPE_MEDIACODEC
  Google Media Codec decoder (.m4a, .mp4). Platform provided decoder, available only on Android.
FMOD_SOUND_TYPE_FADPCM
  FMOD Adaptive Differential Pulse Code Modulation bit-stream supported by FSB (.fsb) container format.
FMOD_SOUND_TYPE_OPUS
  Opus bit-stream supported by FSB (.fsb) container format. Platform provided decoder, available only on Xbox Series X|S.
FMOD_SOUND_TYPE_MAX
  Maximum number of sound types supported.

See Also: Sound::getFormat

## Sound::unlock

Finalizes a previous sample data lock and submits it back to the Sound object.

C
C++
C#
JS

    FMOD_RESULT Sound::unlock(
      void *ptr1,
      void *ptr2,
      unsigned int len1,
      unsigned int len2
    );

    FMOD_RESULT FMOD_Sound_Unlock(
      FMOD_SOUND *sound,
      void *ptr1,
      void *ptr2,
      unsigned int len1,
      unsigned int len2
    );

    RESULT Sound.unlock(
      IntPtr ptr1,
      IntPtr ptr2,
      uint len1,
      uint len2
    );

    Sound.unlock(
      ptr1,
      ptr2,
      len1,
      len2
    );

ptr1

  First part of the locked data.

  - Units: Sample Data
ptr2

  Second part of the locked data.

  - Units: Sample Data
len1

  Length of `ptr1`.

  - Units: Bytes
len2

  Length of `ptr2`

  - Units: Bytes

The data being 'unlocked' must first have been locked with Sound::lock.

If an unlock is not performed on PCM data, then sample loops may produce audible clicks.

The names 'lock'/'unlock' are a legacy reference to older Operating System APIs that used to cause a mutex lock on the data, so that it could not be written to while the 'lock' was in place. This is no longer the case with FMOD and data can be 'locked' multiple times from different places/threads at once.

See Also: Sound::lock

## FMOD_TAG

Tag data / metadata description.

C
C++
C#
JS

    typedef struct FMOD_TAG {
      FMOD_TAGTYPE       type;
      FMOD_TAGDATATYPE   datatype;
      char              *name;
      void              *data;
      unsigned int       datalen;
      FMOD_BOOL          updated;
    } FMOD_TAG;

    struct TAG
    {
      TAGTYPE           type;
      TAGDATATYPE       datatype;
      StringWrapper     name;
      IntPtr            data;
      uint              datalen;
      bool              updated;
    }

    FMOD_TAG
    {
      type,
      datatype,
      data,
      datalen,
      updated,
    };

type R/O
  Tag type. (FMOD_TAGTYPE)
datatype R/O
  Tag data type. (FMOD_TAGDATATYPE)
name R/O
  Name.
data R/O
  Tag data.
datalen R/O
  Size of `data`.
  * Units: Bytes
updated R/O

  True if this tag has been updated since last being accessed with Sound::getTag

  - Units: Boolean

See Also: Sound::getTag

## FMOD_TAGDATATYPE

List of tag data / metadata types.

C
C++
C#
JS

    typedef enum FMOD_TAGDATATYPE {
      FMOD_TAGDATATYPE_BINARY,
      FMOD_TAGDATATYPE_INT,
      FMOD_TAGDATATYPE_FLOAT,
      FMOD_TAGDATATYPE_STRING,
      FMOD_TAGDATATYPE_STRING_UTF16,
      FMOD_TAGDATATYPE_STRING_UTF16BE,
      FMOD_TAGDATATYPE_STRING_UTF8,
      FMOD_TAGDATATYPE_MAX
    } FMOD_TAGDATATYPE;

    enum TAGDATATYPE : int
    {
      BINARY,
      INT,
      FLOAT,
      STRING,
      STRING_UTF16,
      STRING_UTF16BE,
      STRING_UTF8,
      MAX
    }

    FMOD.TAGDATATYPE_BINARY
    FMOD.TAGDATATYPE_INT
    FMOD.TAGDATATYPE_FLOAT
    FMOD.TAGDATATYPE_STRING
    FMOD.TAGDATATYPE_STRING_UTF16
    FMOD.TAGDATATYPE_STRING_UTF16BE
    FMOD.TAGDATATYPE_STRING_UTF8
    FMOD.TAGDATATYPE_MAX

FMOD_TAGDATATYPE_BINARY
  Raw binary data. see FMOD_TAG structure for length of data in bytes.
FMOD_TAGDATATYPE_INT
  Integer - Note this integer could be 8bit / 16bit / 32bit / 64bit. See FMOD_TAG structure for integer size (1 vs 2 vs 4 vs 8 bytes).
FMOD_TAGDATATYPE_FLOAT
  IEEE floating point number. See FMOD_TAG structure to confirm if the float data is 32bit or 64bit (4 vs 8 bytes).
FMOD_TAGDATATYPE_STRING
  8bit ASCII char string. See FMOD_TAG structure for string length in bytes.
FMOD_TAGDATATYPE_STRING_UTF16
  16bit UTF string. Assume little endian byte order. See FMOD_TAG structure for string length in bytes.
FMOD_TAGDATATYPE_STRING_UTF16BE
  16bit UTF string Big endian byte order. See FMOD_TAG structure for string length in bytes.
FMOD_TAGDATATYPE_STRING_UTF8
  8 bit UTF string. See FMOD_TAG structure for string length in bytes.
FMOD_TAGDATATYPE_MAX
  Maximum number of tag datatypes supported.

See FMOD_TAG structure for tag length in bytes.

See Also: Sound::getTag, FMOD_TAGTYPE, FMOD_TAG

## FMOD_TAGTYPE

List of tag data / metadata types that could be stored within a sound. These include id3 tags, metadata from netstreams and vorbis/asf data.

C
C++
C#
JS

    typedef enum FMOD_TAGTYPE {
      FMOD_TAGTYPE_UNKNOWN,
      FMOD_TAGTYPE_ID3V1,
      FMOD_TAGTYPE_ID3V2,
      FMOD_TAGTYPE_VORBISCOMMENT,
      FMOD_TAGTYPE_SHOUTCAST,
      FMOD_TAGTYPE_ICECAST,
      FMOD_TAGTYPE_ASF,
      FMOD_TAGTYPE_MIDI,
      FMOD_TAGTYPE_PLAYLIST,
      FMOD_TAGTYPE_FMOD,
      FMOD_TAGTYPE_USER,
      FMOD_TAGTYPE_MAX
    } FMOD_TAGTYPE;

    enum TAGTYPE
    {
      UNKNOWN,
      ID3V1,
      ID3V2,
      VORBISCOMMENT,
      SHOUTCAST,
      ICECAST,
      ASF,
      MIDI,
      PLAYLIST,
      FMOD,
      USER,
      MAX
    }

    FMOD.TAGTYPE_UNKNOWN
    FMOD.TAGTYPE_ID3V1
    FMOD.TAGTYPE_ID3V2
    FMOD.TAGTYPE_VORBISCOMMENT
    FMOD.TAGTYPE_SHOUTCAST
    FMOD.TAGTYPE_ICECAST
    FMOD.TAGTYPE_ASF
    FMOD.TAGTYPE_MIDI
    FMOD.TAGTYPE_PLAYLIST
    FMOD.TAGTYPE_FMOD
    FMOD.TAGTYPE_USER
    FMOD.TAGTYPE_MAX

FMOD_TAGTYPE_UNKNOWN
  Tag type that is not recognized by FMOD
FMOD_TAGTYPE_ID3V1
  MP3 ID3 Tag 1.0. Typically 1 tag stored 128 bytes from end of an MP3 file.
FMOD_TAGTYPE_ID3V2
  MP3 ID3 Tag 2.0. Variable length tags with more than 1 possible.
FMOD_TAGTYPE_VORBISCOMMENT
  Metadata container used in Vorbis, FLAC, Theora, Speex and Opus file formats.
FMOD_TAGTYPE_SHOUTCAST
  SHOUTcast internet stream metadata which can be issued during playback.
FMOD_TAGTYPE_ICECAST
  Icecast internet stream metadata which can be issued during playback.
FMOD_TAGTYPE_ASF
  Advanced Systems Format metadata typically associated with Windows Media formats such as WMA.
FMOD_TAGTYPE_MIDI
  Metadata stored inside a MIDI file.
FMOD_TAGTYPE_PLAYLIST
  Playlist files such as PLS,M3U,ASX and WAX will populate playlist information through this tag type.
FMOD_TAGTYPE_FMOD
  Tag type used by FMOD's MIDI, MOD, S3M, XM, IT format support, and netstreams to notify of internet stream events like a sample rate change.
FMOD_TAGTYPE_USER
  For codec developers, this tag type can be used with FMOD_CODEC_METADATA_FUNC to generate custom metadata.
FMOD_TAGTYPE_MAX
  Maximum number of tag types supported.

FMOD_TAGTYPE_MIDI remarks. A midi file contains 16 channels. Not all of them are used, or in order. Use the tag 'Channel mask' and 'Number of channels' to find the channels used, to use with Sound::setMusicChannelVolume / Sound::getMusicChannelVolume. For example if the mask is 1001b, there are 2 channels, and channel 0 and channel 3 are the 2 channels used with the above functions.

See Also: Sound::getTag, FMOD_TAGDATATYPE, FMOD_TAG