Struct ears::Sound

pub struct Sound { /* fields omitted */ }

Play Sounds easily.

Simple class to play sounds easily in 2 lines. Sounds are really light objects, the sound's data is entirely loaded into memory and can be shared between Sounds using the SoundData object.

Examples

extern crate ears;
use ears::{Sound, AudioController};

fn main() -> () {
   // Create a Sound with the path of the sound file.
   let mut snd = Sound::new("path/to/my/sound.ogg").unwrap();

   // Play it
   snd.play();

   // Wait until the sound stopped playing
   while snd.is_playing() {}
}

Methods

impl Sound

pub fn new(path: &str) -> Result<Sound, String>

Default constructor for Sound struct.

Create a new struct and an associated SoundData.

Argument

path - The path of the sound file to create the SoundData.

Return

A Result containing Ok(Sound) on success, Err(String) if there has been an error.

Example

use ears::Sound;

let snd = Sound::new("path/to/the/sound.ogg")
                 .expect("Cannot load the sound from a file!");

pub fn new_with_data(
    sound_data: Rc<RefCell<SoundData>>
) -> Result<Sound, String>

Create a new struct with a SoundData to associate.

Argument

sound_data - The sound_data to associate to the Sound.

Return

An Option with Some(Sound) if the Sound is created properly, or None if un error has occured.

Example

use ears::{Sound, SoundData, AudioController};
use std::rc::Rc;
use std::cell::RefCell;

let data = Rc::new(RefCell::new(SoundData::new("path/to/the/sound.ogg").unwrap()))
let sound = Sound::new_with_data(data).unwrap();

pub fn get_datas(&self) -> Rc<RefCell<SoundData>>

Get the sound datas.

Return

The SoundData associated to this Sound.

Example

let snd = ears::Sound::new("path/to/the/sound.ogg").unwrap();
let snd_data = snd.get_datas();

pub fn set_datas(&mut self, sound_data: Rc<RefCell<SoundData>>)

Set the sound datas.

Doesn't work if the sound is currently playing.

Argument

sound_data - The new sound_data

Example

let snd1 = ears::Sound::new("path/to/the/sound.ogg").unwrap();
let mut snd2 = ears::Sound::new("other/path/to/the/sound.ogg").unwrap();
let snd_data = snd1.get_datas();
snd2.set_datas(snd_data);

Trait Implementations

impl AudioTags for Sound

fn get_tags(&self) -> Tags

Get the tags of a Sound.

Return

A borrowed pointer to the internal struct SoundTags

impl AudioController for Sound

fn play(&mut self)

Play or resume the Sound.

Example

use ears::{Sound, AudioController};

let mut snd = Sound::new("path/to/the/sound.ogg").unwrap();
snd.play();

fn pause(&mut self)

Pause the Sound.

Example

use ears::{Sound, AudioController};

let mut snd = Sound::new("path/to/the/sound.ogg").unwrap();
snd.play();
snd.pause();
snd.play(); // the sound restarts at the moment of the pause

fn stop(&mut self)

Stop the Sound.

Example

use ears::{Sound, AudioController};

let mut snd = Sound::new("path/to/the/sound.ogg").unwrap();
snd.play();
snd.stop();
snd.play(); // the sound restart at the begining

fn is_playing(&self) -> bool

Check if the Sound is playing or not.

Return

True if the Sound is playing, false otherwise.

Example

use ears::{Sound, AudioController};

let mut snd = Sound::new("path/to/the/sound.ogg").unwrap();
snd.play();
if snd.is_playing() {
    println!("Sound is Playing !");
} else {
    println!("Sound is Pause or Stopped !");
}

fn get_state(&self) -> State

Get the current state of the Sound

Return

The state of the sound as a variant of the enum State

Example

use ears::{Sound, State, AudioController};

let snd = Sound::new("path/to/the/sound.ogg").unwrap();
match snd.get_state() {
    State::Initial => println!("Sound has never been played"),
    State::Playing => println!("Sound is playing!"),
    State::Paused  => println!("Sound is paused!"),
    State::Stopped => println!("Sound is stopped!")
}

fn set_volume(&mut self, volume: f32)

Set the volume of the Sound.

A value of 1.0 means unattenuated. Each division by 2 equals an attenuation of about -6dB. Each multiplicaton by 2 equals an amplification of about +6dB.

Argument

• volume - The volume of the Sound, should be between 0.0 and 1.0

fn get_volume(&self) -> f32

Get the volume of the Sound.

Return

The volume of the Sound between 0.0 and 1.0

fn set_min_volume(&mut self, min_volume: f32)

Set the minimal volume for a Sound.

The minimum volume allowed for a source, after distance and cone attenation is applied (if applicable).

Argument

• min_volume - The new minimal volume of the Sound should be between 0.0 and 1.0

fn get_min_volume(&self) -> f32

Get the minimal volume of the Sound.

Return

The minimal volume of the Sound between 0.0 and 1.0

fn set_max_volume(&mut self, max_volume: f32)

Set the maximal volume for a Sound.

The maximum volume allowed for a sound, after distance and cone attenation is applied (if applicable).

Argument

• max_volume - The new maximal volume of the Sound should be between 0.0 and 1.0

fn get_max_volume(&self) -> f32

Get the maximal volume of the Sound.

Return

The maximal volume of the Sound between 0.0 and 1.0

fn set_looping(&mut self, looping: bool)

Set the Sound looping or not

The default looping is false.

Arguments

looping - The new looping state.

fn is_looping(&self) -> bool

Check if the Sound is looping or not

Return

true if the Sound is looping, false otherwise.

fn set_pitch(&mut self, pitch: f32)

Set the pitch of the source.

A multiplier for the frequency (sample rate) of the source's buffer.

Default pitch is 1.0.

Argument

• new_pitch - The new pitch of the sound in the range [0.5 - 2.0]

fn get_pitch(&self) -> f32

Set the pitch of the source.

Return

The pitch of the sound in the range [0.5 - 2.0]

fn set_relative(&mut self, relative: bool)

Set the position of the sound relative to the listener or absolute.

Default position is absolute.

Argument

relative - True to set sound relative to the listener false to set the sound position absolute.

fn is_relative(&mut self) -> bool

Is the sound relative to the listener or not ?

Return

True if the sound is relative to the listener false otherwise

fn set_position(&mut self, position: [f32; 3])

Set the Sound location in three dimensional space.

OpenAL, like OpenGL, uses a right handed coordinate system, where in a frontal default view X (thumb) points right, Y points up (index finger), and Z points towards the viewer/camera (middle finger). To switch from a left handed coordinate system, flip the sign on the Z coordinate.

Default position is [0.0, 0.0, 0.0].

Argument

• position - A three dimensional vector of f32 containing the position of the listener [x, y, z].

fn get_position(&self) -> [f32; 3]

Get the position of the Sound in three dimensional space.

Return

A three dimensional vector of f32 containing the position of the listener [x, y, z].

fn set_direction(&mut self, direction: [f32; 3])

Set the direction of the Sound.

Specifies the current direction in local space.

The default direction is: [0.0, 0.0, 0.0]

Argument

direction - The new direction of the Sound.

fn get_direction(&self) -> [f32; 3]

Get the direction of the Sound.

Return

The current direction of the Sound.

fn set_max_distance(&mut self, max_distance: f32)

Set the maximum distance of the Sound.

The distance above which the source is not attenuated any further with a clamped distance model, or where attenuation reaches 0.0 gain for linear distance models with a default rolloff factor.

The default maximum distance is +inf.

Argument

max_distance - The new maximum distance in the range [0.0, +inf]

fn get_max_distance(&self) -> f32

Get the maximum distance of the Sound.

Return

The maximum distance of the Sound in the range [0.0, +inf]

fn set_reference_distance(&mut self, ref_distance: f32)

Set the reference distance of the Sound.

The distance in units that no attenuation occurs. At 0.0, no distance attenuation ever occurs on non-linear attenuation models.

The default distance reference is 1.

Argument

• ref_distance - The new reference distance of the Sound.

fn get_reference_distance(&self) -> f32

Get the reference distance of the Sound.

Return

The current reference distance of the Sound.

fn set_attenuation(&mut self, attenuation: f32)

Set the attenuation of a Sound.

Multiplier to exaggerate or diminish distance attenuation. At 0.0, no distance attenuation ever occurs.

The default attenuation is 1.

Arguments

attenuation - The new attenuation for the sound in the range [0.0, 1.0].

fn get_attenuation(&self) -> f32

Get the attenuation of a Sound.

Return

The current attenuation for the sound in the range [0.0, 1.0].

fn set_direct_channel(&mut self, enabled: bool)

Enable or disable direct channel mode for a Sound.

Sometimes audio tracks are authored with their own spatialization effects, where the AL's virtualization methods can cause a notable decrease in audio quality.

The AL_SOFT_direct_channels extension provides a mechanism for applications to specify whether audio should be filtered according to the AL's channel virtualization rules for multi-channel buffers.

When set to true, the audio channels are not virtualized and play directly on the matching output channels if they exist, otherwise they are dropped. Applies only when the extension exists and when playing non-mono buffers.

http://kcat.strangesoft.net/openal-extensions/SOFT_direct_channels.txt

The default is false.

Argument

• enabled - true to enable direct channel mode, false to disable

fn get_direct_channel(&self) -> bool

Returns whether direct channel is enabled or not for a Sound.

Will always return false if the AL_SOFT_direct_channels extension is not present.

Return

true if the Sound is using direct channel mode false otherwise

impl Drop for Sound

fn drop(&mut self)

Destroy all the resources attached to the Sound.