Skip to content

sound

Jump to bottom
Francisco Dias edited this page Nov 22, 2024 · 4 revisions

Sound

FMOD Object: Sound


This module holds the functionality related to FMOD sounds, which store sample data that can be played on a Channel.

You can create sounds with fmod_system_create_sound or fmod_system_create_stream.

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.


Back To Top

fmod_sound_get_name

FMOD Function: Sound::getName


This function retrieves the name of a sound.


Syntax:

fmod_sound_get_name(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

String



Back To Top

fmod_sound_get_format

FMOD Function: Sound::getFormat


This function returns format information about the sound.


Syntax:

fmod_sound_get_format(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FmodSoundFormat



Back To Top

fmod_sound_get_length

FMOD Function: Sound::getLength


This function retrieves the length using the specified time unit.

length_type must be valid for the file format. For example, an MP3 file does not support FMOD_TIMEUNIT.MODORDER.

A length of 0xFFFFFFFF means the sound 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 untagged MP3 or MOD/S3M/XM/IT) may return inaccurate length values. For these formats, use FMOD_MODE.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.


Syntax:

fmod_sound_get_length(sound_ref, length_type)
Argument Type Description
sound_ref Real A reference to a sound.
length_type FMOD_TIMEUNIT The time unit type to retrieve.



Returns:

Real



Back To Top

fmod_sound_get_num_tags

FMOD Function: Sound::getNumTags


This function retrieves the number of metadata tags.

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

Note

This value 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.


Syntax:

fmod_sound_get_num_tags(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FmodSoundNumTags



Back To Top

fmod_sound_get_tag

FMOD Function: Sound::getTag


This function retrieves a metadata 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 fmod_sound_get_num_tags.

Displaying or retrieving tags can be done in 3 different ways:

  • All tags can be continuously retrieved by looping from 0 to the num_tags value in fmod_sound_get_num_tags - 1. Updated tags will refresh automatically, and the update member of the FmodSoundTag 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 fmod_last_result will return an error of FMOD_RESULT.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 fmod_channel_set_frequency. A sample rate change will be signalled with a tag of type FMOD_TAGTYPE.FMOD.


Syntax:

fmod_sound_get_tag(sound_ref, tag_index, data_buffer)
Argument Type Description
sound_ref Real A reference to a sound.
tag_index Real The index into the tag list.
data_buffer Buffer The Buffer in which to store the raw, binary tag data.



Returns:

FmodSoundTag


Example:

The following example reads any tags that have arrived, this could happen if a radio station switches to a new song. This loop only runs IF there is an update to the tags.

var _tag = fmod_sound_get_tag(sound_index, -1, tag_data_buff);
while (fmod_last_result() == FMOD_RESULT.OK)
{
    // Move cursor to the beginning of the buffer
    buffer_seek(tag_data_buff, buffer_seek_start, 0);

    if (_tag.data_type == FMOD_TAGDATATYPE.STRING)
    {
        var _value = buffer_read(tag_data_buff, buffer_string);
        tag_strings[tag_index] = $"{_tag.name}: {_value}";
        tag_index = (tag_index + 1) % tag_count;

        if (_tag.type == FMOD_TAGTYPE.PLAYLIST && _tag.name == "FILE")
        {
            var _url = _value;
            fmod_sound_release(sound_index);

            sound_index = fmod_system_create_sound(_url, FMOD_MODE.CREATESTREAM | FMOD_MODE.NONBLOCKING, extra);
        }
    }
    else if (_tag.type == FMOD_TAGTYPE.FMOD)
    {
        // When a song changes, the sample rate may also change, so compensate here.
        if ((_tag.name == "Sample Rate Change") && channel_index != -1)
        {
            var _frequency = buffer_read(tag_data_buff, buffer_f32);
            fmod_channel_set_frequency(channel_index, _frequency);
        }
    }

    _tag = fmod_sound_get_tag(sound_index, -1, tag_data_buff);
}


Back To Top

fmod_sound_set_3d_cone_settings

FMOD Function: Sound::set3DConeSettings


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

When fmod_channel_control_set_3d_cone_orientation 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 inside_cone_angle, the sound will not have any attenuation applied.
  • If the relative angle is between the inside_cone_angle and outside_cone_angle, linear volume attenuation (between 1 and outside_volume) is applied between the two angles until it reaches the outside_cone_angle.

Syntax:

fmod_sound_set_3d_cone_settings(sound_ref, inside_cone_angle, outside_cone_angle, outside_volume)
Argument Type Description
sound_ref Real A reference to a sound.
inside_cone_angle Real The inside cone angle, expressed in degrees. This is the angle spread within which the sound is unattenuated. A value in the range [0, 360]. The default is 360.
outside_cone_angle Real The outside cone angle, expressed in degrees. This is the angle spread outside of which the sound is attenuated to its outside_volume. A value in the range [0, 360]. The default is 360.
outside_volume Real The cone outside volume. A value in the range [0, 1]. The default is 1.



Returns:

N/A



Back To Top

fmod_sound_get_3d_cone_settings

FMOD Function: Sound::get3DConeSettings


This function retrieves the inside and outside angles of the 3D projection cone and the outside volume.


Syntax:

fmod_sound_get_3d_cone_settings(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Fmod3DConeSettings



Back To Top

fmod_sound_set_3d_custom_rolloff

FMOD Function: Sound::set3DCustomRolloff


This function sets a custom roll-off shape for 3D distance attenuation.

Note

This function must be used in conjunction with the FMOD_MODE.AS_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_MODE.AS_3D_CUSTOMROLLOFF is set and the roll-off shape is not set, FMOD will revert to FMOD_MODE.AS_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
curve =
[
    { x: 0,  y:  1, z: 0 },
    { x: 2,  y: .2, z: 0 },
    { x: 2,  y:  0, z: 0 }
];

Syntax:

fmod_sound_set_3d_custom_rolloff(sound_ref, points)
Argument Type Description
sound_ref Real A reference to a sound.
points Array of FmodVector An array of points sorted by distance, where x = distance and y = volume from 0 to 1. z should be set to 0.



Returns:

N/A



Back To Top

fmod_sound_get_3d_custom_rolloff

FMOD Function: Sound::get3DCustomRolloff


This function retrieves the current custom roll-off shape for 3D distance attenuation.


Syntax:

fmod_sound_get_3d_custom_rolloff(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Array of FmodVector



Back To Top

fmod_sound_set_3d_min_max_distance

FMOD Function: Sound::set3DMinMaxDistance


This function sets the minimum and maximum audible distance for a 3D sound.

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 fmod_system_create_sound, fmod_system_create_stream, fmod_sound_set_mode or fmod_channel_control_set_mode.

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_MODE.AS_3D_LINEARROLLOFF
  • FMOD_MODE.AS_3D_LINEARSQUAREROLLOFF

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

  • FMOD_MODE.AS_3D_INVERSEROLLOFF
  • FMOD_MODE.AS_3D_INVERSETAPEREDROLLOFF

For this mode the max distance is ignored:

  • FMOD_MODE.AS_3D_CUSTOMROLLOFF

Syntax:

fmod_sound_set_3d_min_max_distance(sound_ref, min, max)
Argument Type Description
sound_ref Real A reference to a sound.
min Real The sound's minimum volume distance, or the distance that the sound has no attenuation due to 3D positioning. The default value is 1.
max Real The sound's maximum volume distance, or the distance that no additional attenuation will occur. See the description for notes on different max distance behaviors. The default value is 10000.



Returns:

N/A



Back To Top

fmod_sound_get_3d_min_max_distance

FMOD Function: Sound::get3DMinMaxDistance


This function retrieves the minimum and maximum audible distance for a 3D sound.


Syntax:

fmod_sound_get_3d_min_max_distance(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FmodMinMaxDistance



Back To Top

fmod_sound_set_defaults

FMOD Function: Sound::setDefaults


This function 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.


Syntax:

fmod_sound_set_defaults(sound_ref, frequency, priority)
Argument Type Description
sound_ref Real A reference to a sound.
frequency Real The default playback frequency, in Hertz. The default is 48000.
priority Real The default priority where 0 is the highest priority. A value in the range [0, 256]. The default is 128.



Returns:

Real



Back To Top

fmod_sound_get_defaults

FMOD Function: Sound::getDefaults


This function retrieves a sound's default playback attributes.


Syntax:

fmod_sound_get_defaults(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FmodSoundDefaults



Back To Top

fmod_sound_set_mode

FMOD Function: Sound::setMode


This function sets or alters the mode of a sound.

Note

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

Note

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

Flags supported:

FMOD_MODE.LOOP_OFF FMOD_MODE.LOOP_NORMAL FMOD_MODE.LOOP_BIDI FMOD_MODE.AS_3D_HEADRELATIVE FMOD_MODE.AS_3D_WORLDRELATIVE FMOD_MODE.AS_2D * FMOD_MODE.AS_3D FMOD_MODE.AS_3D_INVERSEROLLOFF FMOD_MODE.AS_3D_LINEARROLLOFF FMOD_MODE.AS_3D_LINEARSQUAREROLLOFF FMOD_MODE.AS_3D_INVERSETAPEREDROLLOFF FMOD_MODE.AS_3D_CUSTOMROLLOFF FMOD_MODE.AS_3D_IGNOREGEOMETRY

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


Syntax:

fmod_sound_set_mode(sound_ref, mode)
Argument Type Description
sound_ref Real A reference to a sound.
mode FMOD_MODE The mode bits to set. The default is FMOD_MODE.DEFAULT.



Returns:

N/A



Back To Top

fmod_sound_get_mode

FMOD Function: Sound::getMode


This function retrieves the mode of a sound.

Note

The mode will be dependent on the mode set by a call to fmod_system_create_sound, fmod_system_create_stream or fmod_sound_set_mode.


Syntax:

fmod_sound_get_mode(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FMOD_MODE



Back To Top

fmod_sound_set_loop_count

FMOD Function: Sound::setLoopCount


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

Note

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


Syntax:

fmod_sound_set_loop_count(sound_ref, count)
Argument Type Description
sound_ref Real A reference to a sound.
count Real The number of times to loop before final playback where -1 is always loop. 0 means no loop. Default is -1.



Returns:

N/A



Back To Top

fmod_sound_get_loop_count

FMOD Function: Sound::getLoopCount


This function retrieves the sound's loop count.

The value -1 is returned when the sound loops infinitely. The value 0 means don't loop.

Note

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


Syntax:

fmod_sound_get_loop_count(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_set_loop_points

FMOD Function: Sound::setLoopPoints


This function sets the loop points within a sound.

The values used for loop_start and loop_end are inclusive, which means these positions will be played.

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

Note

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

Note

The Sound's mode must be set to FMOD_MODE.LOOP_NORMAL or FMOD_MODE.LOOP_BIDI for loop points to affect playback.


Syntax:

fmod_sound_set_loop_points(sound_ref, loop_start, loop_start_type, loop_end, loop_end_type)
Argument Type Description
sound_ref Real A reference to a sound.
loop_start Real The loop start point. A value in the range [0, loop_end].
loop_start_type FMOD_TIMEUNIT The time format of loop_start.
loop_end Real The loop end point. A value in the range [loop_start, fmod_sound_get_length].
loop_end_type FMOD_TIMEUNIT The time format of loop_end.



Returns:

N/A



Back To Top

fmod_sound_get_loop_points

FMOD Function: Sound::getLoopPoints


This function retrieves the loop points for a sound.

The values from loop_start and loop_end are inclusive, which means these positions will be played.


Syntax:

fmod_sound_get_loop_points(sound_ref, loop_start_type, loop_end_type)
Argument Type Description
sound_ref Real A reference to a sound.
loop_start_type FMOD_TIMEUNIT The time format in which to return loop_start.
loop_end_type FMOD_TIMEUNIT The time format in which to return loop_end.



Returns:

FmodLoopPoints



Back To Top

fmod_sound_set_sound_group

FMOD Function: Sound::setSoundGroup


This function moves the sound from its existing SoundGroup to the specified sound group.

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


Syntax:

fmod_sound_set_sound_group(sound_ref, sound_group_ref)
Argument Type Description
sound_ref Real A reference to a sound.
sound_group_ref Real The sound group to move the sound to.



Returns:

N/A



Back To Top

fmod_sound_get_sound_group

FMOD Function: Sound::getSoundGroup


This function retrieves the sound's current sound group.


Syntax:

fmod_sound_get_sound_group(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_get_num_sub_sounds

FMOD Function: Sound::getNumSubSounds


This function retrieves the number of subsounds stored within a sound.

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


Syntax:

fmod_sound_get_num_sub_sounds(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_get_sub_sound

FMOD Function: Sound::getSubSound


This function retrieves a handle to a Sound object that is contained within the parent sound.

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

If FMOD_MODE.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_MODE.NONBLOCKING is used, until the state of the sound becomes FMOD_OPENSTATE.READY or FMOD_OPENSTATE.ERROR.


Syntax:

fmod_sound_get_sub_sound(sound_ref, sub_sound_index)
Argument Type Description
sound_ref Real A reference to a sound.
sub_sound_index Real The index of the subsound.



Returns:

Real



Back To Top

fmod_sound_get_sub_sound_parent

FMOD Function: Sound::getSubSoundParent


This function retrieves the parent Sound object that contains this subsound.

If the sound is not a subsound, the value returned will be 0.


Syntax:

fmod_sound_get_sub_sound_parent(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_get_open_state

FMOD Function: Sound::getOpenState


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

When a sound is opened with FMOD_MODE.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 fmod_channel_control_set_mute will keep the stream quiet until it is not starving anymore.

Note

Always check open_state to determine the state of the sound. Do not assume that if this function returns FMOD_RESULT.OK then the sound has finished loading.

See also: FMOD_MODE


Syntax:

fmod_sound_get_open_state(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

FmodSoundOpenState



Back To Top

fmod_sound_read_data

FMOD Function: Sound::readData


This function reads data from an opened sound to a specified Buffer, using FMOD's internal codecs.

It returns the actual number of bytes written to the buffer or -1 in case of an error.

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 fmod_sound_lock / fmod_sound_unlock the data.

If you read too much data, it is possible that fmod_last_result will return FMOD_RESULT.ERR_FILE_EOF, meaning it is out of data. The returned '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 fmod_system_create_sound, fmod_sound_read_data will then not work because the file handle is closed. Use FMOD_MODE.OPENONLY to stop FMOD reading/decoding the file. If FMOD_MODE.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_MODE.OPENONLY to stop the stream pre-buffering or call fmod_sound_seek_data 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. fmod_channel_set_position 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 fmod_sound_seek_data and not the previously mentioned functions.

If you are calling fmod_sound_read_data and fmod_sound_seek_data on a stream, information functions such as fmod_channel_get_position may give misleading results. Calling fmod_channel_get_position will cause the streaming engine to reset and flush the stream, leading to the time values returning to their correct position.


Syntax:

fmod_sound_read_data(sound_ref, buff, length, offset)
Argument Type Description
sound_ref Real A reference to a sound.
buff Buffer The Buffer to read the decoded data into.
length Real The length of the data to read into the buffer, in bytes.
offset Real The offset in the buffer, in bytes, to write the data.



Returns:

Real



Back To Top

fmod_sound_seek_data

FMOD Function: Sound::seekData


This function seeks a sound for use with data reading, using FMOD's internal codecs.

Warning

This function is for use in conjunction with fmod_sound_read_data and FMOD_MODE.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 fmod_channel_set_position. This causes reset and flush of the stream buffer.


Syntax:

fmod_sound_seek_data(sound_ref, pcm)
Argument Type Description
sound_ref Real A reference to a sound.
pcm Real The seek offset, in samples.



Returns:

N/A



Back To Top

fmod_sound_lock

FMOD Function: Sound::lock


This function gives access to a portion or all the sample data of a sound for direct manipulation.

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.

The locked data is copied to the buffers that you pass to the function. This can be two buffers as the data may "wrap around" to the start of the sound. The first buffer will always store the data up to the end of the sound. The second will store the remainder, starting at the start of the sound. If the range of data you want to copy doesn't exceed the length of the sound the second buffer will have no data written to it.

You can lock multiple regions of data of a sound at the same time, but you should make sure the regions don't overlap. If some bytes are locked by multiple calls to this function, they will remain locked after you make all corresponding calls to fmod_sound_unlock.

Important

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

If the sound is created with FMOD_MODE.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_last_result will return FMOD_RESULT.ERR_SUBSOUNDS.
  • A stream / sound created with FMOD_MODE.CREATESTREAM. FMOD_RESULT.ERR_BADCOMMAND will be returned by fmod_last_result in this case.

Syntax:

fmod_sound_lock(sound_ref, offset, length, buff1, buff2)
Argument Type Description
sound_ref Real A reference to a sound.
offset Real The offset into the sound's buffer to be retrieved, in bytes.
length Real The length of the data required to be retrieved.
buff1 Buffer The buffer to write the first part of the locked data to.
buff2 Buffer The buffer to write the second part of the locked data to. This will only be written to if the offset + length has exceeded the length of the sample buffer.



Returns:

FmodSoundLock



Back To Top

fmod_sound_unlock

FMOD Function: Sound::unlock


This function finalizes a previous sample data lock and submits it back to the Sound object.

The data being 'unlocked' must first have been locked with fmod_sound_lock.

Warning

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


Syntax:

fmod_sound_unlock(sound_ref, buff1, len1, address1, buff2, len2, address2)
Argument Type Description
sound_ref Real A reference to a sound.
buff1 Real The first buffer passed to an earlier call to fmod_sound_lock.
len1 Real The length of the data in the first buffer, in bytes.
address1 Real The patch_address of buffer1's corresponding chunck in FMOD memory, as returned by an earlier call to fmod_sound_lock.
buff2 Real OPTIONAL The second buffer passed to an earlier call to fmod_sound_lock.
len2 Real OPTIONAL The length of the data in the second buffer, in bytes.
address2 Real OPTIONAL The patch_address of buffer2's corresponding chunck in FMOD memory, as returned by an earlier call to fmod_sound_lock.



Returns:

N/A



Back To Top

fmod_sound_get_music_num_channels

FMOD Function: Sound::getMusicNumChannels


This function gets the number of music channels inside a MOD/S3M/XM/IT/MIDI file.


Syntax:

fmod_sound_get_music_num_channels(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_set_music_channel_volume

FMOD Function: Sound::setMusicChannelVolume


This function sets the volume of a MOD/S3M/XM/IT/MIDI music channel volume.


Syntax:

fmod_sound_set_music_channel_volume(sound_ref, channel_index, volume)
Argument Type Description
sound_ref Real A reference to a sound.
channel_index Real The MOD/S3M/XM/IT/MIDI music subchannel to set a linear volume for.
volume Real The volume of the channel. A value in the range [0, 1]. Default is 1.



Returns:

N/A



Back To Top

fmod_sound_get_music_channel_volume

FMOD Function: Sound::getMusicChannelVolume


This function retrieves the volume of a MOD/S3M/XM/IT/MIDI music channel volume.


Syntax:

fmod_sound_get_music_channel_volume(sound_ref, channel_index)
Argument Type Description
sound_ref Real A reference to a sound.
channel_index Real The MOD/S3M/XM/IT/MIDI music subchannel to retrieve the volume for.



Returns:

Real



Back To Top

fmod_sound_set_music_speed

FMOD Function: Sound::setMusicSpeed


This function sets the relative speed of MOD/S3M/XM/IT/MIDI music.


Syntax:

fmod_sound_set_music_speed(sound_ref, speed)
Argument Type Description
sound_ref Real A reference to a sound.
speed Real The speed of the song. A value in the range [0.01, 100]. The default is 1.



Returns:

N/A



Back To Top

fmod_sound_get_music_speed

FMOD Function: Sound::getMusicSpeed


This function gets the relative speed of MOD/S3M/XM/IT/MIDI music.


Syntax:

fmod_sound_get_music_speed(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_get_sync_point

FMOD Function: Sound::getSyncPoint


This function retrieves a sync point.

For more information on sync points see Sync Points.


Syntax:

fmod_sound_get_sync_point(sound_ref, point_index, offset_type)
Argument Type Description
sound_ref Real A reference to a sound.
point_index Real The index of the sync point. A value in the range [0, fmod_sound_get_num_sync_points - 1].
offset_type FMOD_TIMEUNIT The format in which to return the sync point offset.



Returns:

FmodSyncPoint



Back To Top

fmod_sound_get_num_sync_points

FMOD Function: Sound::getNumSyncPoints


This function retrieves the number of sync points stored within a sound.

For more information on sync points see Sync Points.


Syntax:

fmod_sound_get_num_sync_points(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_add_sync_point

FMOD Function: Sound::addSyncPoint


This function adds a sync point at a specific time within the sound.

For more information on sync points see Sync Points.


Syntax:

fmod_sound_add_sync_point(sound_ref, offset, offset_type, name)
Argument Type Description
sound_ref Real A reference to a sound.
offset Real The offset value.
offset_type FMOD_TIMEUNIT The offset unit type.
name String The sync point name.



Returns:

N/A



Back To Top

fmod_sound_delete_sync_point

FMOD Function: Sound::deleteSyncPoint


This function deletes a sync point within the sound.

For more information on sync points see Sync Points.


Syntax:

fmod_sound_delete_sync_point(sound_ref, point_index)
Argument Type Description
sound_ref Real A reference to a sound.
point_index FmodSyncPoint The sync point.



Returns:

N/A



Back To Top

fmod_sound_release

FMOD Function: Sound::release


This function frees a sound object.

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_MODE.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 fmod_sound_get_open_state and checking the open state for FMOD_OPENSTATE.READY and FMOD_OPENSTATE.ERROR is a good way to avoid stalls.


Syntax:

fmod_sound_release(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

N/A



Back To Top

fmod_sound_get_system_object

FMOD Function: Sound::getSystemObject


This function retrieves the parent System object.


Syntax:

fmod_sound_get_system_object(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



Back To Top

fmod_sound_set_user_data

FMOD Function: Sound::setUserData


This function sets a floating-point user value associated with this object.

Note

While FMOD supports arbitrary User Data, this function only allows you to set a real value (a double-precision floating-point value).


Syntax:

fmod_sound_set_user_data(sound_ref, data)
Argument Type Description
sound_ref Real A reference to a sound.
data Real The value to be stored on this object.



Returns:

N/A



Back To Top

fmod_sound_get_user_data

FMOD Function: Sound::getUserData


This function retrieves a user value associated with this object, set with fmod_sound_set_user_data.

Note

While FMOD allows arbitrary User Data, this function only allows you to get a real value (a double-precision floating-point value).


Syntax:

fmod_sound_get_user_data(sound_ref)
Argument Type Description
sound_ref Real A reference to a sound.



Returns:

Real



YoYoGames 2024

FMOD Extension

Guides

FMOD Core Reference

FMOD Studio Reference

Extras

Clone this wiki locally