FMOD Engine User Manual 2.03
Container for sample data that can be played on a Channel.
Create with System::createSound or System::createStream.
Format information:
Defaults when played:
Relationship management:
Data reading:
Music:
Synchronization / markers:
General:
These values describe what state a sound is in after FMOD_NONBLOCKING has been used to open it.
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
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
Adds a sync point at a specific time within the sound.
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 unit type. (FMOD_TIMEUNIT)For more information on sync points see Sync Points.
See Also: Sound::getNumSyncPoints, Sound::getSyncPoint, Sound::getSyncPointInfo, Sound::deleteSyncPoint
Deletes a sync point within the sound.
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
);
For for more information on sync points see Sync Points.
See Also: Sound::addSyncPoint, Sound::getNumSyncPoints, Sound::getSyncPoint
These definitions describe the native format of the hardware or software buffer that will be used.
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
See Also: System::createSound, Sound::getFormat
Retrieves the inside and outside angles of the 3D projection cone and the outside volume.
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
);
Inside cone angle. This is the angle within which the sound is unattenuated.
outsideconeangle]Outside cone angle. This is the angle outside of which the sound is attenuated to its outside volume.
insideconeangle, 360]Cone outside volume.
See Also: Sound::set3DConeSettings
Retrieves the current custom roll-off shape for 3D distance attenuation.
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.See Also: Sound::set3DCustomRolloff
Retrieve the minimum and maximum audible distance for a 3D sound.
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
);
Minimum volume distance for the sound.
Maximum volume distance for the sound.
See Also: Sound::set3DMinMaxDistance
Retrieves a sound's default playback attributes.
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
);
Default playback frequency.
Default priority where 0 is the highest priority.
See Also: Sound::setDefaults
Returns format information about the sound.
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
);
format.Retrieves the length using the specified time unit.
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
);
lengthtype.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
Retrieves the sound's loop count.
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
);
Number of times to loop before final playback where -1 is always loop. 0 means no loop.
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
Retrieves the loop points for a sound.
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. (FMOD_TIMEUNIT)loopend. (FMOD_TIMEUNIT)The values from loopstart and loopend are inclusive, which means these positions will be played.
See Also: Sound::setLoopPoints
Retrieves the mode of a sound.
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
);
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
Retrieves the volume of a MOD/S3M/XM/IT/MIDI music channel volume.
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
);
Volume of the channel.
See Also: Sound::setMusicChannelVolume
Gets the number of music channels inside a MOD/S3M/XM/IT/MIDI file.
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
);
See Also: Sound::setMusicChannelVolume, Sound::getMusicChannelVolume
Gets the relative speed of MOD/S3M/XM/IT/MIDI music.
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
);
See Also: Sound::setMusicSpeed
Retrieves the name of a sound.
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
);
Length of buffer to receive name.
if FMOD_LOWMEM has been specified in System::createSound, this function will return "(null)".
Retrieves the number of subsounds stored within a sound.
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
);
A format that has subsounds is a container format, such as FSB, DLS, MOD, S3M, XM, IT.
See Also: Sound::getSubSound
Retrieves the number of sync points stored within a sound.
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
);
For for more information on sync points see Sync Points.
See Also: Sound::getSyncPoint, Sound::getSyncPointInfo, Sound::addSyncPoint, Sound::deleteSyncPoint
Retrieves the number of metadata tags.
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
);
'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
Retrieves the state a sound is in after being opened with the non blocking flag, or the current state of the streaming buffer.
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
);
Filled percentage of a stream's file buffer.
Starving state. true if a stream has decoded more than the stream file buffer has ready.
Disk is currently being accessed for this sound.
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
Retrieves the sound's current sound group.
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
);
See Also: Sound::setSoundGroup, System::getMasterSoundGroup
Retrieves a handle to a Sound object that is contained within the parent sound.
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 of the subsound.
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
Retrieves the parent Sound object that contains this subsound.
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
);
If the sound is not a subsound, the parentsound will be null.
See Also: Sound::getNumSubSounds, Sound::getSubSound
Retrieve a sync point.
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 of the sync point.
For for more information on sync points see Sync Points.
See Also: Sound::getNumSyncPoints, Sound::getSyncPointInfo, Sound::addSyncPoint, Sound::deleteSyncPoint
Retrieves information on an embedded sync point.
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
);
Size of name.
offset. (FMOD_TIMEUNIT)For for more information on sync points see Sync Points.
See Also: Sound::getNumSyncPoints, Sound::getSyncPoint, Sound::addSyncPoint, Sound::deleteSyncPoint
Retrieves the parent System object.
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
);
See Also: System::createSound
Retrieves a metadata tag.
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
);
Index into the tag list as restricted by name.
'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:
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);
}
}
}
Retrieves a user value associated with this object.
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
);
This function allows arbitrary user data to be retrieved from this object. See the User Data section of the glossary for an example of how to get and set user data.
Gives access to a portion or all the sample data of a sound for direct manipulation.
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 into the sound's buffer to be retrieved.
Length of the data required to be retrieved. If offset + length exceeds the length of the sample buffer, ptr2 and len2 will be valid.
First part of the locked data.
Second part of the locked data if the offset + length has exceeded the length of the sample buffer.
Length of ptr1.
Length of ptr2
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
Callback to be called when a sound has finished loading, or a non blocking seek is occuring.
FMOD_RESULT F_CALL FMOD_SOUND_NONBLOCK_CALLBACK(
FMOD_SOUND *sound,
FMOD_RESULT result
);
delegate RESULT SOUND_NONBLOCKCALLBACK(
IntPtr sound,
RESULT result
);
Not supported for JavaScript.
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
Read callback used for user created sounds or to intercept FMOD's decoder during a normal sound open.
FMOD_RESULT F_CALL 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
)
Length of the data.
Invoked by:
Use cases:
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
Set position callback for user created sounds or to intercept FMOD's decoder during an API setPositon call.
FMOD_RESULT F_CALL 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
)
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
Reads data from an opened sound to a specified buffer, using FMOD's internal codecs.
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(
byte[] buffer
);
RESULT Sound.readData(
byte[] buffer,
out uint read
);
Sound.readData(
buffer,
length,
read
);
Buffer to read decoded data into.
Amount of data to read into buffer.
Actual amount of data read. May differ to length.
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: Extracting PCM Data from a Sound, Sound::lock, Sound::unlock
Frees a sound object.
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. Additionally, if the sound is still playing or has recently been stopped, the release may stall, as the mixer may still be using the sound. 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
Seeks a sound for use with data reading, using FMOD's internal codecs.
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
);
Seek Offset.
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.
Sets the angles and attenuation levels of a 3D cone shape, for simulated occlusion which is based on direction.
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
);
Inside cone angle. This is the angle spread within which the sound is unattenuated.
outsideconeangle]Outside cone angle. This is the angle spread outside of which the sound is attenuated to its outsidevolume.
insideconeangle, 360]Cone outside volume.
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.
insideconeangle, the sound will not have any attenuation applied.insideconeangle and outsideconeangle, linear volume attenuation (between 1 and outsidevolume) is applied between the two angles until it reaches the outsideconeangle.outsideconeangle the volume does not attenuate any further.See Also: Sound::get3DConeSettings, ChannelControl::set3DConeSettings
Sets a custom roll-off shape for 3D distance attenuation.
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
);
x = distance and y = volume from 0 to 1. z should be set to 0. Pass null or equivalent to disable custom roll-off. (FMOD_VECTOR)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 roll-off shape is not set, FMOD will revert to FMOD_3D_INVERSEROLLOFF roll-off mode.
When a custom roll-off 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
Sets the minimum and maximum audible distance for a 3D sound.
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
);
The sound's minimum volume distance, or the distance that the sound has no attenuation due to 3d positioning.
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 roll-off 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
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.
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
);
Default playback frequency.
Default priority where 0 is the highest priority.
See Also: Sound::getDefaults, System::playSound, System::createSound
Sets the sound to loop a specified number of times before stopping if the playback mode is set to looping.
FMOD_RESULT Sound::setLoopCount(
int loopcount
);
FMOD_RESULT FMOD_Sound_SetLoopCount(
FMOD_SOUND *sound,
int loopcount
);
RESULT Sound.setLoopCount(
int loopcount
);
Sound.setLoopCount(
loopcount
);
Number of times to loop before final playback where -1 is always loop. 0 means no loop.
Changing loop count on an already buffered stream may not produced desired output. See Streaming Issues.
See Also: Sound::setLoopPoints, Sound::getLoopCount
Sets the loop points within a sound.
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
);
Loop start point.
loopstart. (FMOD_TIMEUNIT)Loop end point.
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.
The Sound's mode must be set to FMOD_LOOP_NORMAL or FMOD_LOOP_BIDI for loop points to affect playback.
See Also: Sound::getLoopPoints, Sound::setLoopCount, Sound::setMode
Sets or alters the mode of a sound.
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 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
Sets the volume of a MOD/S3M/XM/IT/MIDI music channel volume.
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
);
Volume of the channel.
See Also: Sound::getMusicNumChannels, Sound::getMusicChannelVolume
Sets the relative speed of MOD/S3M/XM/IT/MIDI music.
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 of the song.
See Also: Sound::getMusicSpeed
Moves the sound from its existing SoundGroup to the specified sound group.
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
);
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
Sets a user value associated with this object.
FMOD_RESULT Sound::setUserData(
void *userdata
);
FMOD_RESULT FMOD_Sound_SetUserData(
FMOD_SOUND *sound,
void *userdata
);
RESULT Sound.setUserData(
IntPtr userdata
);
Sound.setUserData(
userdata
);
This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.
See Also: Sound::getUserData
Recognized audio formats that can be loaded into a Sound.
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
See Also: Sound::getFormat
Finalizes a previous sample data lock and submits it back to the Sound object.
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
);
First part of the locked data.
Second part of the locked data.
Length of ptr1.
Length of ptr2
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
Tag data / metadata description.
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,
};
data.
* Units: BytesTrue if this tag has been updated since last being accessed with Sound::getTag
See Also: Sound::getTag
List of tag data / metadata types.
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
See FMOD_TAG structure for tag length in bytes.
See Also: Sound::getTag, FMOD_TAGTYPE, FMOD_TAG
List of tag data / metadata types that could be stored within a sound. These include id3 tags, metadata from netstreams and vorbis/asf data.
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_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