Crate rfmod[−][src]
Expand description
rust-fmod
This is a rust binding for FMOD, the library developped by FIRELIGHT TECHNOLOGIES.
FMOD website: <www.fmod.org>
Installation
You must install on your computer the FMOD library which is used for the binding.
Short example
Here is a short example on how to create a file and to play it:
extern crate libc;
extern crate rfmod;
use std::os;
fn main() {
let fmod = match rfmod::Sys::new() {
Ok(f) => f,
Err(e) => {
panic!("Error code : {}", e);
}
};
match fmod.init() {
rfmod::Status::Ok => {}
e => {
panic!("Sys.init failed : {}", e);
}
};
let mut sound = match fmod.create_sound(StrBuf::from_str("music.mp3"), None, None) {
Ok(s) => s,
Err(err) => {
panic!("Error code : {}", err);
}
};
match sound.play_to_the_end() {
rfmod::Status::Ok => {
println!("Ok !");
}
err => {
panic!("Error code : {}", err);
}
};
}
For a more complete example: https://github.com/GuillaumeGomez/rust-music-player
License
Copyright (c) 2014 Guillaume Gomez
The license of this project is available in the LICENSE.TXT file. Please refer to it.
If you want more information, here is the website for FMOD : http://www.fmod.org/
Notes
- Members marked with [r] mean the variable is modified by FMOD and is for reading purposes only. Do not change this value.
- Members marked with [w] mean the variable can be written to. The user can set the value.
Here is the list of all modules :
Re-exports
pub use self::types::Mode;pub use self::types::TimeUnit;pub use self::types::FmodCaps;pub use self::types::PluginHandle;pub use self::types::InitFlag;pub use self::types::MemoryBits;pub use self::types::EventMemoryBits;Modules
Macros
Structs
Settings for advanced features like configuring memory and cpu usage for the FMOD_CREATECOMPRESSEDSAMPLE feature.
Channel Object
ChannelGroup object
Use this structure with Sys::create_sound when more
control is needed over loading. The possible reasons to use this with
Sys::create_sound are:
Dsp object
DspConnection object
When creating a DSP unit, declare one of these and provide the relevant callbacks and name for FMOD to use when it creates and uses a DSP unit of this type.
Structure to define a parameter for a DSP unit.
DSP plugin structure that is passed into each callback.
A little struct to wrap C files.
Wrapper for SyncPoint object
Structure describing a piece of tag data.
Geometry object
Structure describing a globally unique identifier.
Structure to be filled with detailed memory usage information of a FMOD object
Wrapper for OutputHandle
Reverb object
Structure defining the properties for a reverb source, related to a FMOD channel.
Structure defining a reverb environment.
Wrapper for arguments of
Sys::set_software_format and
Sys::get_software_format.
Sound object
SoundGroup object
Structure which contains data for
Channel::set_speaker_mix and
Channel::get_speaker_mix
FMOD System Object
Structure used to store user data for file callback
Structure describing a point in 3D space.
Enums
Special channel index values for FMOD functions.
Types of delay that can be used with
Channel::set_delay /
Channel::get_delay.
Parameter types for the FMOD_DSP_TYPE_CHORUS filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_COMPRESSOR unit.
This is a simple linked multichannel software limiter that is uniform across the whole spectrum.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_DELAY filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_DISTORTION filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
List of windowing methods used in spectrum analysis to reduce leakage / transient signals intefering with the analysis. This is a problem with analysis of continuous signals that only have a small portion of the signal sample (the fft window size). Windowing the signal with a curve or triangle tapers the sides of the fft window to help alleviate this problem.
Parameter types for the FMOD_DSP_TYPE_FLANGE filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_HIGHPASS filter.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the FMOD_DSP_TYPE_HIGHPASS_SIMPLE filter.
This is a very simple single-order high pass filter.
The emphasis is on speed rather than accuracy, so this should not be used for task requiring
critical filtering.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the FMOD_DSP_TYPE_ITECHO filter.
This is effectively a software based echo filter that emulates the DirectX DMO echo effect.
Impulse tracker files can support this, and FMOD will produce the effect on ANY platform, not
just those that support DirectX effects!
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_ITLOWPASS filter.
This is different to the default FMOD_DSP_TYPE_ITLOWPASS filter in that it uses a different
quality algorithm and is the filter used to produce the correct sounding playback in .IT files.
FMOD Ex’s .IT playback uses this filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_LOWPASS filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_LOWPASS_SIMPLE filter.
This is a very simple low pass filter, based on two single-pole RC time-constant modules.
The emphasis is on speed rather than accuracy, so this should not be used for task requiring
critical filtering.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the FMOD_DSP_TYPE_NORMALIZE filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_OSCILLATOR filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
Parameter types for the FMOD_DSP_TYPE_PITCHSHIFT filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
List of interpolation types that the FMOD Ex software mixer supports.
Parameter types for the FMOD_DSP_TYPE_SFXREVERB unit.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the FMOD_DSP_TYPE_TREMOLO filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
These definitions can be used for creating FMOD defined special effects or DSP units.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the DspTypeEcho filter.
Used with Dsp::set_parameter and
Dsp::get_parameter.
Parameter types for the DspTypeParameq filter.
Used with Dsp::set_parameter and
Dsp::get_parameter
These values describe what state a sound is in after FMOD_NONBLOCKING has been used to open it.
These output types are used with Sys::set_output /
Sys::get_output, to choose which output method to use.
These are plugin types defined for use with the
Sys::get_num_plugins,
Sys::get_plugin_info and
Sys::unload_plugin functions.
These definitions describe the native format of the hardware or software buffer that will be used.
These flags are used with
SoundGroup::set_max_audible_behavior
to determine what happens when more sounds are played than are specified with
SoundGroup::set_max_audible.
These definitions describe the type of song being played.
These are speaker types defined for use with the
Channel::set_speaker_level command. It
can also be used for speaker placement in the
Sys::set_3D_speaker_position command.
When creating a multichannel sound, FMOD will pan them to their default speaker locations:
These are speaker types defined for use with the
Sys::set_speaker_mode or
Sys::get_speaker_mode command.
Error codes. Returned from every function.
These callback types are used with
Channel::set_callback.
List of data types that can be returned by
Sound::get_tag
List of tag types that could be stored within a sound. These include id3 tags, metadata from netstreams and vorbis/asf data.
Constants
For Sys::create_sound - for accurate Sound::get_length / Channel::set_position on VBR MP3, and MOD/S3M/XM/IT/MIDI files. Scans file first, so takes longer to open. OPENONLY does not affect this.
Load MP2/MP3/IMAADPCM/CELT/Vorbis/AT9 or XMA into memory and leave it compressed. CELT/Vorbis/AT9 encoding only supported in the FSB file format. During playback the FMOD software mixer will decode it in realtime as a ‘compressed sample’. Can only be used in combination with SOFTWARE. Overrides CREATESAMPLE. If the sound data is not one of the supported formats, it will behave as if it was created with CREATESAMPLE and decode the sound into PCM.
Decompress at loadtime, decompressing or decoding whole file into memory as the target sample format (ie PCM). Fastest for SOFTWARE based playback and most flexible.
Decompress at runtime, streaming from the source provided (ie from disk). Overrides CREATESAMPLE and CREATECOMPRESSEDSAMPLE. Note a stream can only be played once at a time due to a stream only having 1 stream buffer and file handle. Open multiple streams to have them play concurrently.
Default for all modes listed below. LOOP_OFF, 2D, HARDWARE
All memory used by FMOD Event System
Event category objects
Event envelope objects
Event envelope definition objects
Event envelope point objects
EventGroup objects and internals
Event instance base objects
Event instance pool data
Complex event instance objects
All event instance memory
Event layer instance objects
Simple event instance objects
Event sound instance objects
Event parameter objects
EventProject objects and internals
Reverb objects
EventSystem and various internals
Definition of objects contained in all loaded projects e.g. events, groups, categories
Data loaded with preloadFSB
MusicSystem and various internals
Reverb definition objects
Objects used to manage wave banks
Data used to manage lists of wave bank usage
Sound definition objects
Sound definition static data objects
Sound definition pool data
All sound definition memory
Stream objects and internals
User property objects
Attempts to make sounds use hardware acceleration. (DEFAULT). Note on platforms that don’t support HARDWARE (only 3DS, PS Vita, PSP, Wii and Wii U support HARDWARE), this will be internally treated as SOFTWARE.
Skips id3v2/asf/etc tag checks when opening a sound, to reduce seek/read overhead when opening files (helps with CD performance).
All platforms - FMOD will treat +X as right, +Y as up and +Z as backwards (towards you).
PS3/PS4 only - FMOD uses the WAVEFORMATEX Microsoft 7.1 speaker mapping where the last 2 pairs of speakers are ‘rears’ then ‘sides’, but on PS3/PS4 these are mapped to ‘surrounds’ and ‘backs’. Use this flag to swap fmod’s last 2 pair of speakers on PS3/PS4 to avoid needing to do a special case for these platforms.
Wii / 3DS - Disable Dolby Pro Logic surround. will be set to STEREO even if user has selected surround in the system settings.
Win32 - Disables automatic setting of of _STEREO to _MYEARS if the MyEars profile exists on the PC. MyEars is HRTF 7.1 downmixing through headphones.
All platforms - All SOFTWARE with 3D based voices will add a software lowpass and highpass filter effect into the DSP chain which will act as a distance-automated bandpass filter. Use Sys::set_advanced_settings to adjust the center frequency.
All platforms - Enable TCP/IP based host which allows FMOD Designer or FMOD Profiler to connect to it, and view memory, CPU and the DSP network graph in real-time.
All platforms - With the geometry engine, only process the closest polygon rather than accumulating all polygons the sound to listener line intersects.
All platforms - All SOFTWARE (and HARDWARE on 3DS and NGP) with 3D based voices will add a software lowpass filter effect into the DSP chain which causes sounds to sound duller when the sound goes behind the listener. Use Sys::set_advanced_settings to adjust Cutoff frequency.
All platforms - Initialize normally
All platforms - All SOFTWARE (and HARDWARE on 3DS and NGP) with 3D based voices will add a software lowpass filter effect into the DSP chain which is automatically used when Channel::set_3D_occlusion is used or the geometry API.
PS3 only - Disable Dolby Digital output mode selection
PS3 only - Disable DTS output mode selection
PS3 only - Force PS3 system output mode to 2 channel LPCM.
PS3 only - Prefer DTS over Dolby Digital if both are supported. Note: 8 and 6 channel LPCM is always preferred over both DTS and Dolby Digital.
All platforms - FMOD Software reverb will preallocate enough buffers for reverb per channel, rather than allocating them and freeing them at runtime.
All platforms - Disable software mixer to save memory. Anything created with SOFTWARE will fail and DSP will not work.
All platforms - No stream thread is created internally. Streams are driven from Sys::update. Mainly used with non-realtime outputs.
Win32/Wii/PS3/Xbox/Xbox 360 - FMOD Mixer thread is woken up to do a mix when Sys::update is called rather than waking periodically on its own timer.
Xbox 360 / PS3 - The “music” channelgroup which by default pauses when custom 360 dashboard / PS3 BGM music is played, can be changed to mute (therefore continues playing) instead of pausing, by using this flag.
All platforms - Any sounds that are 0 volume will go virtual and not be processed except for having their positions updated virtually. Use Sys::set_advanced_settings to adjust what volume besides zero to switch to virtual at.
Win32 Vista only - for WASAPI output - Enable exclusive access to hardware, lower latency at the expense of excluding other applications from accessing the audio hardware.
Load sound into the secondary RAM of supported platform. On PS3, sounds will be loaded into RSX/VRAM.
For bidirectional looping sounds. (only works on software mixed static sounds).
For forward looping sounds.
For non looping sounds. (DEFAULT). Overrides LOOP_NORMAL / LOOP_BIDI.
Removes some features from samples to give a lower memory overhead, like Sound::get_name. See remarks.
All memory used by FMOD Ex
Channel related memory
ChannelGroup objects and internals
Codecs allocated for streaming
Dsp implementation objects
Realtime file format decoding Dsp objects
DspConnection objects and internals
Codecs allocated for streaming
Geometry objects and internals
Memory not accounted for by other types
Output module object and internals
Plugin objects and internals
Profiler memory footprint.
Buffer used to store recorded data from microphone
Reverb implementation objects
Reverb channel properties structs
Sound objects and internals
SoundGroup objects and internals
Sound data stored in secondary RAM
Stream buffer memory
String data
Sync point memory.
Sys object and various internals
For corrupted / bad MP3 files. This will search all the way through the file until it hits a valid MPEG header. Normally only searches for 4k.
For opening sounds and getting streamed subsounds (seeking) asyncronously. Use Sound::get_open_state to poll the state of the sound as it opens or retrieves the subsound in the background.
“name_or_data” will be interpreted as a pointer to memory instead of filename for creating sounds. Use CREATESOUNDEXINFO to specify length. If used with CREATESAMPLE or CREATECOMPRESSEDSAMPLE, FMOD duplicates the memory into its own buffers. Your own buffer can be freed after open. If used with CREATESTREAM, FMOD will stream out of the buffer whose pointer you passed in. In this case, your own buffer should not be freed until you have finished with and released the stream.
“name_or_data” will be interpreted as a pointer to memory instead of filename for creating sounds. Use CREATESOUNDEXINFO to specify length. This differs to OPENMEMORY in that it uses the memory as is, without duplicating the memory into its own buffers. For Wii/PSP HARDWARE supports this flag for the GCADPCM/VAG formats. On other platforms SOFTWARE must be used, as sound hardware on the other platforms (ie PC) cannot access main ram. Cannot be freed after open, only after Sound::release. Will not work if the data is compressed and CREATECOMPRESSEDSAMPLE is not used.
Just open the file, dont prebuffer or read. Good for fast opens for info, or when sound::readData is to be used.
Will ignore file format and treat as raw pcm. Use CREATESOUNDEXINFO to specify format. Requires at least defaultfrequency, numchannels and format to be specified before it will open. Must be little endian data.
Opens a user created static sample or stream. Use CREATESOUNDEXINFO to specify format and/or read callbacks. If a user created ‘sample’ is created with no read callback, the sample will be empty. Use Sound::lock and Sound::unlock to place sound data into the sound if this is the case.
Makes the sound be mixed by the FMOD CPU based software mixer. Overrides HARDWARE. Use this for FFT, DSP, compressed sample support, 2D multi-speaker support and other software related features.
Time value as seen by buffered stream. This is always ahead of audible time, and is only used for processing.
MOD/S3M/XM/IT. Order in a sequenced module format. Use Sound::get_format to determine the PCM format being decoded to.
MOD/S3M/XM/IT. Current pattern in a sequenced module format. Sound::get_length will return the number of patterns in the song and Channel::get_position will return the currently playing pattern.
MOD/S3M/XM/IT. Current row in a sequenced module format. Sound::get_length will return the number of rows in the currently playing or seeked to pattern.
Milliseconds.
PCM samples, related to milliseconds * samplerate / 1000.
Bytes, related to PCM samples * channels * datawidth (ie 16bit = 2 bytes).
Fractions of 1 PCM sample. Unsigned int range 0 to 0xFFFFFFFF. Used for sub-sample granularity for DSP purposes.
Raw file bytes of (compressed) sound data (does not include headers). Only used by Sound::get_length and Channel::get_position.
Currently playing sentence index according to the channel.
Currently playing subsound in a sentence time in milliseconds.
Currently playing subsound in a sentence time in PCM Samples, related to milliseconds * samplerate / 1000.
Currently playing subsound in a sentence time in bytes, related to PCM samples * channels * datawidth (ie 16bit = 2 bytes).
Currently playing subsound index in a sentence.
Filename is double-byte unicode.
Unique sound, can only be played one at a time
For sounds that start virtual (due to being quiet or low importance), instead of swapping back to audible, and playing at the correct offset according to time, this flag makes the sound play from the start.
Ignores any 3d processing. (DEFAULT).
Makes the sound positionable in 3D. Overrides 2D
This sound will follow a rolloff model defined by Sound::set_3D_custom_rolloff / Channel::set_3D_custom_rolloff.
Make the sound’s position, velocity and orientation relative to the listener.
Is not affect by geometry occlusion. If not specified in Sound::set_mode, or Channel::set_mode, the flag is cleared and it is affected by geometry again.
This sound will follow the inverse rolloff model where mindistance = full volume, maxdistance = where sound stops attenuating, and rolloff is fixed according to the global rolloff factor. (DEFAULT)
This sound will follow a linear rolloff model where mindistance = full volume, maxdistance = silence. Rolloffscale is ignored.
This sound will follow a linear-square rolloff model where mindistance = full volume, maxdistance = silence. Rolloffscale is ignored.
Make the sound’s position, velocity and orientation absolute (relative to the world). (DEFAULT)