Struct Sound

pub struct Sound { /* private fields */ }

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

Create with System::create_sound or System::create_stream.

Implementations

impl Sound

pub fn get_open_state(&self) -> Result<(OpenState, c_uint, bool, bool)>

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_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 Ok then the sound has finished loading.

pub unsafe fn lock( &self, offset: c_uint, length: c_uint, ) -> Result<SoundLock<'_>>

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.

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

It is not possible to lock the following:

• A parent sound containing subsounds. A parent sound has no audio data and Error::Subsounds will be returned.
• A stream / sound created with FMOD_CREATESTREAM. Error::BadCommand will be returned in this case.

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

Safety

While SoundLock’s lifetime is tied to self, it’s a very loose coupling because Sound is Copy! If FMOD frees the memory pointed to by SoundLock, it’s insta UB.

Don’t call FMOD_Sound_Unlock with the pointers from SoundLock. SoundLock will do that for you when dropped.

pub unsafe fn read_data(&self, buffer: &mut [u8]) -> Result<c_uint>

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 the data.

If too much data is read, it is possible Error::FileEof 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::create_sound, Sound::read_data 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::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. 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 Sound::seek_data and not the previously mentioned functions.

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

Safety

If you call this from another stream callback, or any other thread besides the main thread, make sure to synchronize 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.

pub fn seek_data(&self, pcm: c_uint) -> Result<()>

For use in conjunction with Sound::read_data 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::set_position. This causes reset and flush of the stream buffer.

impl Sound

pub fn set_3d_cone_settings( &self, inside_angle: c_float, outside_angle: c_float, outside_volume: c_float, ) -> Result<()>

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

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 inside_angle, the sound will not have any attenuation applied.
• If the relative angle is between the inside_angle and outside_angle, linear volume attenuation (between 1 and outside_volume) is applied between the two angles until it reaches the outside_angle.
• If the relative angle is outside of the outside_angle the volume does not attenuate any further.

pub fn get_3d_cone_settings(&self) -> Result<(c_float, c_float, c_float)>

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

pub unsafe fn set_3d_custom_rolloff(&self, points: &mut [Vector]) -> Result<()>

Sets a custom roll-off shape for 3D distance attenuation.

Must be used in conjunction with Mode::CUSTOM_ROLLOFF_3D flag to be activated.

If Mode::CUSTOM_ROLLOFF_3D is set and the roll-off shape is not set, FMOD will revert to Mode::INVERSE_ROLLOFF_3D roll-off mode.

When a custom roll-off is specified a Channel or ChannelGroup’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.

Safety

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

pub fn get_3d_custom_rolloff(&self) -> Result<Vec<Vector>>

Retrieves the current custom roll-off shape for 3D distance attenuation.

pub fn set_3d_min_max_distance(&self, min: c_float, max: c_float) -> Result<()>

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 System::create_sound, System::create_stream, Sound::setMode or ChannelControl::setMode.

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

• FMOD_3D_LINEARROLLOFF
• FMOD_3D_LINEARSQUAREROLLOFF

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

• FMOD_3D_INVERSEROLLOFF
• FMOD_3D_INVERSETAPEREDROLLOFF

For this mode the max distance is ignored:

• FMOD_3D_CUSTOMROLLOFF

pub fn get_3d_min_max_distance(&self) -> Result<(c_float, c_float)>

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

pub fn set_defaults(&self, frequency: c_float, priority: c_int) -> Result<()>

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.

pub fn get_defaults(&self) -> Result<(c_float, c_int)>

Retrieves a sound’s default playback attributes.

pub fn set_mode(&self, mode: Mode) -> Result<()>

Sets or alters the mode of a sound.

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:

• Mode::LOOP_OFF
• Mode::LOOP_NORMAL
• Mode::LOOP_BIDI
• Mode::HEADRELATIVE_3D
• Mode::WORLDRELATIVE_3D
• Mode::D2
• Mode::D3
• Mode::INVERSE_ROLLOFF_3D
• Mode::LINEAR_ROLLOFF_3D
• Mode::LINEAR_SQUARE_ROLLOFF_3D
• Mode::INVERSE_TAPERED_ROLLOFF_3D
• Mode::CUSTOM_ROLLOFF_3D
• Mode::IGNORE_GEOMETRY_3D

If Mode::IGNORE_GEOMETRY_3D 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.

pub fn get_mode(&self) -> Result<Mode>

Retrieves the mode of a sound.

The mode will be dependent on the mode set by a call to System::create_sound, System::create_stream or Sound::set_mode.

pub fn set_loop_count(&self, loop_count: c_int) -> Result<()>

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

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

pub fn get_loop_count(&self) -> Result<c_int>

Retrieves the sound’s loop count.

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

pub fn set_loop_points( &self, loop_start: c_uint, start_type: TimeUnit, loop_end: c_uint, end_type: TimeUnit, ) -> Result<()>

Sets the loop points within a sound.

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

If a loop_end 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 Mode::LOOP_NORMAL or Mode::LOOP_BIDI for loop points to affect playback.

pub fn get_loop_points( &self, start_type: TimeUnit, end_type: TimeUnit, ) -> Result<(c_uint, c_uint)>

Retrieves the loop points for a sound.

The values returned are inclusive, which means these positions will be played.

impl Sound

pub fn release(&self) -> Result<()>

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_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::get_open_state and checking the open state for FMOD_OPENSTATE_READY and FMOD_OPENSTATE_ERROR is a good way to avoid stalls.

pub fn set_userdata(&self, userdata: *mut c_void) -> Result<()>

Sets the user data.

pub fn get_userdata(&self) -> Result<*mut c_void>

Retrieves user data.

pub fn get_system(&self) -> Result<System>

Retrieves the parent System object.

impl Sound

pub fn get_name(&self) -> Result<Utf8CString>

Retrieves the name of a sound.

If FMOD_LOWMEM has been specified in System::create_sound, this function will return “(null)”.

pub fn get_format(&self) -> Result<(SoundType, SoundFormat, c_int, c_int)>

Returns format information about the sound.

pub fn get_length(&self, unit: TimeUnit) -> Result<c_uint>

Retrieves the length using the specified time unit.

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.

pub fn get_tag_count(&self) -> Result<(c_int, c_int)>

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.

The second tuple field 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.

pub fn get_tag(&self, name: Option<&Utf8CStr>, index: c_int) -> Result<Tag>

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

 while let Ok(tag) = sound->getTag(None, -1)
 {
   if matches!(tag.type, TagType::Fmod) {
     // When a song changes, the sample rate may also change, so compensate here.
     if tag.name == "Sample Rate Change" && channel {
       let TagDataType::Float(frequency) = tag.data else {
         break
       };
       result = channel.set_frequency(frequency)?;
     }
   }
 }

impl Sound

pub fn get_music_channel_count(&self) -> Result<i32>

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

pub fn set_music_channel_volume( &self, channel: c_int, volume: c_float, ) -> Result<()>

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

pub fn get_music_channel_volume(&self, channel: c_int) -> Result<c_float>

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

pub fn set_music_speed(&self, speed: c_float) -> Result<()>

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

pub fn get_music_speed(&self) -> Result<c_float>

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

impl Sound

pub fn set_sound_group(&self, group: SoundGroup) -> Result<()>

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 System::getMasterSoundGroup.

pub fn sound_group(&self) -> Result<SoundGroup>

Retrieves the sound’s current sound group.

pub fn get_sub_sound_count(&self) -> Result<c_int>

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.

pub fn get_sub_sound(&self, index: c_int) -> Result<Sound>

Retrieves a handle to a Sound object that is contained within the parent 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.

pub fn get_sub_sound_parent(&self) -> Result<Option<Sound>>

Retrieves the parent Sound object that contains this subsound.

impl Sound

pub fn get_sync_point(&self, index: i32) -> Result<SyncPoint>

Retrieve a sync point.

For for more information on sync points see Sync Points.

pub fn get_sync_point_info( &self, point: SyncPoint, offset_type: TimeUnit, ) -> Result<(Utf8CString, c_uint)>

Retrieves information on an embedded sync point.

For for more information on sync points see Sync Points.

pub fn get_sync_point_count(&self) -> Result<i32>

Retrieves the number of sync points stored within a sound.

For for more information on sync points see Sync Points.

pub fn add_sync_point( &self, offset: c_uint, offset_type: TimeUnit, name: &Utf8CStr, ) -> Result<SyncPoint>

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

For more information on sync points see Sync Points.

pub fn delete_sync_point(&self, point: SyncPoint) -> Result<()>

Deletes a sync point within the sound.

For for more information on sync points see Sync Points.

impl Sound

pub unsafe fn from_ffi(value: *mut FMOD_SOUND) -> Self

Safety

value must be a valid pointer either aquired from Self::as_ptr or FMOD.

Panics

Panics if value is null.

pub fn as_ptr(self) -> *mut FMOD_SOUND

Converts self into its raw representation.

Trait Implementations

impl Clone for Sound

fn clone(&self) -> Sound

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Sound

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Sound> for *mut FMOD_SOUND

fn from(value: Sound) -> Self

Converts to this type from the input type.

impl Hash for Sound

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Sound

fn eq(&self, other: &Sound) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Sound

impl Eq for Sound

impl Send for Sound

Available on non-crate feature thread-unsafe only.

impl StructuralPartialEq for Sound

impl Sync for Sound

Available on non-crate feature thread-unsafe only.