English中文
Core API Reference | Sound

FMOD API User Manual 2.00

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:

  • FMOD_TAG Tag data / metadata description.
  • FMOD_SOUND_TYPE These definitions describe the type of song being played.
  • 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:

Relationship management:

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:

Synchronization / markers:

General:

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;
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
);
offset
Offset value.
offsettype
offset unit type. (FMOD_TIMEUNIT)
name Opt
Sync point name. (UTF-8 string)
point OutOpt
Sync point. (FMOD_SYNCPOINT)

For 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
);
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;
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
);
insideconeangle OutOpt

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

  • Units: Degrees
  • Range: [0, outsideconeangle]
  • Default: 360
outsideconeangle OutOpt

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 OutOpt

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
);
points OutOpt
Array of points sorted by distance where x = distance and y = volume from 0 to 1. (FMOD_VECTOR)
numpoints OutOpt
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
);
min OutOpt

Minimum volume distance for the sound.

max OutOpt

Maximum volume distance for the sound.

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
);
frequency OutOpt

Default playback frequency.

  • Units: Hertz
  • Default: 48000
priority OutOpt

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
);
type OutOpt
Type of sound. (FMOD_SOUND_TYPE)
format OutOpt
Format of the sound. (FMOD_SOUND_FORMAT)
channels OutOpt
Number of channels.
bits OutOpt
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
);
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
);
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
);
loopstart OutOpt
Loop start point.
loopstarttype
Time format of loopstart. (FMOD_TIMEUNIT)
loopend OutOpt
Loop end point.
loopendtype
Time format of loopend. (FMOD_TIMEUNIT)

The values from loopstart' andloopend` 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
);
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
);
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
);
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
);
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
);
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
);
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
);
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
);
numtags OutOpt
Number of tags.
numtagsupdated OutOpt
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
);
openstate OutOpt
Open state of a sound. (FMOD_OPENSTATE)
percentbuffered OutOpt

Filled percentage of a stream's file buffer.

  • Units: Percent
  • Range: [0, 100]
starving OutOpt

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

  • Units: Boolean
diskbusy OutOpt

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
);
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
);
index

Index of the subsound.

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
);
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
);
index

Index of the sync point.

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
);
point
Sync point. (FMOD_SYNCPOINT)
name OutOpt
Name of the syncpoint. (UTF-8 string)
namelen

Size of name.

  • Units: Bytes
offset OutOpt
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
);
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
);
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.

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 (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
);
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
);
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.

ptr2 Out

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

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:

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
);
sound
Sound. (Sound)
result
Error code. (FMOD_RESULT)

Invoked by:

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
);
sound
Sound. (Sound)
data
PCM data that the user can either read or write to.
datalen

Length of the data.

  • Units: Bytes

Invoked by:

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
);
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)

Invoked by:

Use cases:

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
);
buffer

Buffer to read decoded data into.

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 function 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();

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
);
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 be 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
);
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
);
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
);
min

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

max

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

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:

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

For this mode the max distance is ignored:

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
);
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
);
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
);
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' andloopend` 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
);
mode
Mode bits to set. (FMOD_MODE)

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:

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
);
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
);
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
);
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
);
userdata
Value stored on this object.

Associates some data with this object to give it context.

See Also: Sound::getUserData

FMOD_SOUND_TYPE

These definitions describe the type of song being played.

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;
FMOD_SOUND_TYPE_UNKNOWN
3rd party / unknown plugin format.
FMOD_SOUND_TYPE_AIFF
AIFF.
FMOD_SOUND_TYPE_ASF
Microsoft Advanced Systems Format (ie WMA/ASF/WMV).
FMOD_SOUND_TYPE_DLS
Sound font / downloadable sound bank.
FMOD_SOUND_TYPE_FLAC
FLAC lossless codec.
FMOD_SOUND_TYPE_FSB
FMOD Sample Bank.
FMOD_SOUND_TYPE_IT
Impulse Tracker.
FMOD_SOUND_TYPE_MIDI
MIDI.
FMOD_SOUND_TYPE_MOD
Protracker / Fasttracker MOD.
FMOD_SOUND_TYPE_MPEG
MP2/MP3 MPEG.
FMOD_SOUND_TYPE_OGGVORBIS
Ogg vorbis.
FMOD_SOUND_TYPE_PLAYLIST
Information only from ASX/PLS/M3U/WAX playlists
FMOD_SOUND_TYPE_RAW
Raw PCM data.
FMOD_SOUND_TYPE_S3M
ScreamTracker 3.
FMOD_SOUND_TYPE_USER
User created sound.
FMOD_SOUND_TYPE_WAV
Microsoft WAV.
FMOD_SOUND_TYPE_XM
FastTracker 2 XM.
FMOD_SOUND_TYPE_XMA
Xbox One XMA
FMOD_SOUND_TYPE_AUDIOQUEUE
iPhone hardware decoder, supports AAC, ALAC and MP3.
FMOD_SOUND_TYPE_AT9
PS4 ATRAC 9 format
FMOD_SOUND_TYPE_VORBIS
Vorbis
FMOD_SOUND_TYPE_MEDIA_FOUNDATION
Windows Store Application built in system codecs
FMOD_SOUND_TYPE_MEDIACODEC
Android MediaCodec
FMOD_SOUND_TYPE_FADPCM
FMOD Adaptive Differential Pulse Code Modulation
FMOD_SOUND_TYPE_OPUS
Opus
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
);
ptr1

First part of the locked 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;
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;
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;
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

FMOD API User Manual 2.00.22 (2021-12-20). © 2021 Firelight Technologies Pty Ltd.

     

© 2026 Firelight Technologies Pty Ltd | Made in Melbourne